How to use the command 'turbo' (with examples)

The ’turbo’ command represents a high-performance build system tailored for JavaScript and TypeScript codebases. Designed to streamline the build process, it enhances efficiency by optimizing task execution and leveraging caching strategies. It’s particularly beneficial for developers working within the fast-paced ecosystem of JavaScript applications, especially those using the Vercel platform. The tool facilitates seamless integration with Vercel capabilities, providing an elevated development experience with robust build and caching support.

Use case: Log in using the default web browser with a Vercel account

Code:

turbo login

Motivation:
The command turbo login is essential for developers who intend to leverage the power of Vercel’s infrastructure. By logging in, you authenticate your identity and ensure that your build system is linked to your Vercel account. This authentication is a prerequisite for utilizing features like remote caching and organizational links which can significantly enhance development workflow and integrity.

Explanation:
The argument login is used to initiate the authentication process. When you execute this command, a browser window will open, prompting you to grant permission to access your Vercel account. This is an integral step in permitting ’turbo’ to use Vercel’s services.

Example output:
A successful login will typically not produce visible output in the terminal but rather complete the OAuth process in your web browser. You might see a confirmation message in the browser indicating that the login was successful.

Use case: Link the current directory to a Vercel organization and enable remote caching

Code:

turbo link

Motivation:
Linking a project ensures that it is recognized under a specific Vercel organization, which is invaluable in team settings. Enabling remote caching allows the ’turbo’ command to use previously computed outputs in future builds, drastically reducing time and computational resources required for builds. Organizations can benefit immensely from this optimized cache-sharing capability.

Explanation:
Here, link takes the current directory and associates it with your Vercel organization. This is especially useful if you’re working in a collaborative environment where multiple team members are contributing to a shared codebase. Remote caching is automatically enabled during this process.

Example output:
On successful linking, you may see a message like “Successfully linked project to [Organization Name] with remote caching enabled.”

Use case: Build the current project

Code:

turbo run build

Motivation:
Building a project is one of the routine tasks in software development. The command turbo run build is leveraged to compile and bundle the application, preparing it for deployment or further integration testing. Ensuring that the build process is quick and efficient significantly affects the developer’s productivity and project delivery timeline.

Explanation:
The command run instructs ’turbo’ to execute a specific script. Here, build is a common script defined in your project’s package.json scripts, which generally denotes compiling the project’s source code into an executable form. This command will benefit from turbo’s efficient handling of tasks to speed up the build process.

Example output:
This would vary depending on the project’s configuration but typically you’ll see a series of log messages detailing the build steps and possibly a final confirmation message such as “Build completed successfully.”

Use case: Run a task without concurrency

Code:

turbo run task_name --concurrency=1

Motivation:
In some cases, running tasks concurrently may lead to race conditions or other synchronization issues within dependent scripts. Utilizing a single-threaded approach, achieved by setting concurrency to one, can mitigate these potential conflicts and ensure tasks are handled in a serialized manner.

Explanation:
The task_name should be replaced with the specific task you want to run. The option --concurrency=1 sets the maximum number of concurrent task executions to one, effectively serializing the execution flow.

Example output:
You’ll see sequential outputs for each step in the task, processed in order, without parallel overlaps. An example might show each log message following after the previous one completes, meaning the process is serialized.

Use case: Run a task ignoring cached artifacts and forcibly re-execute all tasks

Code:

turbo run task_name --force

Motivation:
Sometimes, it is necessary to ensure that every aspect of a task runs fresh, perhaps due to configuration changes or suspected cache corruption. The --force option allows developers to bypass any existing cached results and ensure tasks are run entirely from scratch, which guarantees that all current changes are incorporated.

Explanation:
The task_name points to the specific task you want to forcibly execute. The --force modifier directs ’turbo’ to ignore all existing caches. This guarantees complete task re-execution and ensures the build reflects the most current state.

Example output:
The output would resemble a standard task execution, barring any reference to utilizing cache, with each step executed as if for the first time.

Use case: Run a task in parallel across packages

Code:

turbo run task_name --parallel --no-cache

Motivation:
Running tasks in parallel is essential in improving build times, especially in monorepo environments where multiple packages need tasks executed. By utilizing the --parallel and --no-cache options together, you ensure all tasks are fresh and executed simultaneously across different packages, providing efficiency gains where cache misses are acceptable.

Explanation:
The task_name is a placeholder for the script you wish to execute. The --parallel option allows ’turbo’ to execute the task across packages simultaneously, while the --no-cache flag ensures that these tasks do not rely on any cached results.

Example output:
You might see interleaved outputs of different task executions, showing them running simultaneously across various packages.

Use case: Unlink the current directory from your Vercel organization and disable Remote Caching

Code:

turbo unlink

Motivation:
There might be scenarios where a project should no longer be associated with a particular Vercel organization, perhaps due to organizational changes or a project migration. The unlink command disassociates the directory from the organization and disables any remote caching previously enabled, resetting the project state.

Explanation:
The unlink command removes the link between the current directory’s project and the associated Vercel organization, ensuring that no further remote caching occurs from this directory.

Example output:
“Successfully unlinked project from [Organization Name] and remote caching disabled” might be a typical message following this command’s execution.

Use case: Generate a Dot graph of a specific task execution

Code:

turbo run task_name --graph=path/to/file.html|jpg|json|pdf|png|svg

Motivation:
Visualizing a task execution flow can be insightful for optimizing build processes and understanding task dependencies. The --graph option generates a dot-graph representation of the task’s execution, thereby aiding in tracking bottlenecks and improving clarity about task orchestration.

Explanation:
The task_name specifies which task you want to visualize. --graph=path/to/file denotes the targeted output path and file format, giving flexibility in how the graph is stored and viewed—be it as HTML, JPG, JSON, PDF, PNG, or SVG.

Example output:
The specified output file in the chosen format will contain the visual representation of the task execution, with nodes representing tasks and edges illustrating their dependencies and execution order.

Conclusion:

The ’turbo’ command is not only a powerful tool for building JavaScript and TypeScript projects but also an integral component in creating efficient development and build workflows. Its functionalities, from linking projects to Vercel organizations to running tasks in parallel, enable developers to optimize their processes and address challenges efficiently. By leveraging examples from logging in to generating execution graphs, developers can utilize ’turbo’ to its fullest potential.