Turborepo
Getting started

Add to an existing repository

Turborepo can be incrementally adopted in any repository, single or multi-package, to speed up the developer and CI workflows of the repository.

After installing turbo and configuring your tasks in turbo.json, you'll notice how caching helps you run tasks much faster.

Preparing a single-package workspace

A single-package workspace is, for example, what you get after running npx create-next-app or npm create vite. You don't need to do any extra work for Turborepo to handle your repo so you can jump to the first step below.

To learn more about Turborepo in single-package workspaces, visit the dedicated guide.

Preparing a multi-package workspace (monorepo)

turbo is built on top of Workspaces, a feature of the major package managers in the JavaScript ecosystem. This makes it easy to adopt in your existing codebase.

Good to know:

If you're finding that turbo is having issues like not being able to discover packages in your workspace or not following your dependency graph, visit our Structuring a repository page for tips.

Note that you don't have to start running all your tasks for all your packages using turbo right away. You can start with a single task in just a few packages and incrementally add more tasks and packages as you get more familiar with Turborepo.

Adding Turborepo to your repository

Install turbo

We recommend you install turbo both globally and into your repository's root for the best developer experience.

Terminal
# Global install
npm install turbo --global
# Install in repository
npm install turbo --save-dev

To learn more about why we recommend both installations, visit the Installation page.

Add a turbo.json file

In the root of your repository, create a turbo.json file.

We'll be using build and check-types tasks in this guide but you can replace these with other tasks that interest you, like lint or test.

./turbo.json
{
  "$schema": "https://turbo.build/schema.json",
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": [".next/**", "!.next/cache/**"]
    },
    "check-types": {
      "dependsOn": ["^check-types"]
    },
    "dev": {
      "persistent": true,
      "cache": false
    }
  }
}

For more information on configuring your turbo.json, see the Configuration Options documentation.

In your Next.js application, make sure you have a check-types script for turbo to run.

apps/web/package.json
{
  "scripts": {
+   "check-types": "tsc --noEmit"
  }
}

In a multi-package workspace, you may also want to add a check-types script to one or more of your library packages to see how multiple scripts across different packages run with one turbo command.

Edit .gitignore

Add .turbo to your .gitignore file. The turbo CLI uses these folders for persisting logs, outputs, and other functionality.

.gitignore
+ .turbo

Add a packageManager field to root package.json

Turborepo optimizes your repository using information from your package manager. To declare which package manager you're using, add a packageManager field to your root package.json if you don't have one already.

package.json
{
+  "packageManager": "npm@8.5.0"
}

Good to know:

Depending on your repository, you may need to use the dangerouslyDisablePackageManagerCheck while migrating or in situations where you can't use the packageManager key yet.

Run tasks with turbo

You can now run the tasks you added to turbo.json earlier using Turborepo. Using the example tasks from above:

Terminal
turbo build check-types

This runs the build and check-types tasks at the same time. The dependency graph of your Workspace will be used to run tasks in the right order.

Without making any changes to the code, try running build and check-types again:

Terminal
turbo check-types build

You should see terminal output like this:

Terminal
 Tasks:    2 successful, 2 total
Cached:    2 cached, 2 total
  Time:    185ms >>> FULL TURBO

Congratulations! You just built and type checked your code in milliseconds.

To learn more about how turbo makes this possible, check out the caching documentation.

Begin developing by running dev with turbo

In a multi-package workspace, you can run turbo dev to start the development tasks for all your packages at once.

Terminal
turbo dev

You can also use a filter to focus on a specific package and its dependencies.

Note that this step doesn't provide much value in a single-package workspace since:

  • You don't cache the outputs for a development task.
  • There's only one development script so there's nothing to run in parallel.

Next steps

You now up and running with Turborepo! To learn about more ways you can improve your workflow and get the most out of turbo, we recommend checking out the following pages:

Previous

Installation

Next

Editor integration

hours

Total Compute Saved
Get started with
Remote Caching →

On this page

Preparing a single-package workspacePreparing a multi-package workspace (monorepo)Adding Turborepo to your repositoryInstall turboAdd a turbo.json fileEdit .gitignoreAdd a packageManager field to root package.jsonRun tasks with turboBegin developing by running dev with turboNext steps