Add Turborepo to your existing monorepo

Configure workspaces

turbo is built on top of Workspaces, a way of managing multiple packages from within a single monorepo package. Turborepo is compatible with the workspace implementations from all package managers. For more information on managing your Turborepo workspaces, see the Workspaces documentation.

You can configure workspaces any way you want, but a common folder structure example is keeping applications in the /apps folder and packages in the /packages folder. The configuration of these folders is different for each package manager.

{
  "workspaces": ["packages/*", "apps/*"]
}

After configuring your workspaces, re-run your package manager's install command.

Install turbo

Install turbo globally.

npm install turbo --global

For more details about installation, see Installing Turborepo

Create turbo.json

In the root of your monorepo, create an empty file named turbo.json. This will hold the configuration for Turborepo.

{
  "$schema": "https://turbo.build/schema.json"
}

Create a pipeline

To define your monorepo's task dependency graph, use the pipeline key in the turbo.json configuration file at the root of monorepo. turbo interprets this configuration to optimally schedule, execute, and cache the outputs of each of the package.json scripts defined in your workspaces.

Each key in the pipeline object is the name of a package.json script that can be executed by turbo run. You can specify its dependencies with the dependsOn key inside it as well as some other options related to caching. For more information on configuring your pipeline, see the Pipelines documentation.

Workspaces that do not have the specified script defined in their package.json's list of scripts will be ignored by turbo.

{
  "$schema": "https://turbo.build/schema.json",
  "pipeline": {
    "build": {
      // A package's `build` script depends on that package's
      // dependencies and devDependencies
      // `build` tasks  being completed first
      // (the `^` symbol signifies `upstream`).
      "dependsOn": ["^build"],
      // note: output globs are relative to each package's `package.json`
      // (and not the monorepo root)
      "outputs": [".next/**", "!.next/cache/**"]
    },
    "deploy": {
      // A package's `deploy` script depends on the `build`,
      // `test`, and `lint` scripts of the same package
      // being completed. It also has no filesystem outputs.
      "dependsOn": ["build", "test", "lint"]
    },
    "test": {
      // A package's `test` script depends on that package's
      // own `build` script being completed first.
      "dependsOn": ["build"],
      // A package's `test` script should only be rerun when
      // either a `.tsx` or `.ts` file has changed in `src` or `test` folders.
      "inputs": ["src/**/*.tsx", "src/**/*.ts", "test/**/*.ts", "test/**/*.tsx"]
    },
    // A package's `lint` script has no dependencies and
    // can be run whenever. It also has no filesystem outputs.
    "lint": {},
    "dev": {
      "cache": false,
      "persistent": true
    }
  }
}

The rough execution order for a given package is based on the dependsOn keys:

1. build once its upstream dependencies have run their build commands
2. test once its own build command is finished and has no filesystem outputs (just logs) within a package
3. lint runs in an arbitrary order as it has no upstream dependencies
4. deploy once its own build, test, and lint commands have finished.

After execution, the full pipeline can run:

npx turbo run deploy

turbo will then schedule the execution of each task(s) to optimize usage of the machine's resources.

Edit .gitignore

Add .turbo to your .gitignore file. The CLI uses these folders for logs and certain task outputs.

+ .turbo

Make sure that your task artifacts, the files and folders you want cached, are also included in your .gitignore.

+ build/**
+ dist/**
+ .next/**

Re-run your npm client's install command to check your configuration.

Build your monorepo

turbo build

Depending on your monorepo setup, some artifacts might already be caching properly. In the next sections, we'll show how turbo works, how scope works, and then how to get caching working after that.

Configure Remote Caching

A major key 🔑 to Turborepo's speed is that it is both lazy and efficient—it does the least amount of work possible and it tries to never redo work that's already been done before.

At the moment, Turborepo caches your tasks on your local filesystem (i.e. "single-player mode," if you will). However, what if there was a way to take advantage of the computational work done by your teammates or your CI (i.e. "co-op multiplayer mode")? What if there was a way to teleport and share a single cache across machines? Almost like a "Dropbox" for your Turborepo cache.

Remote Caching has entered the chat.

Turborepo can use a technique known as Remote Caching to share cache artifacts across machines for an additional speed boost.

Using Remote Caching for Local development

Turborepo uses Vercel (opens in a new tab) as its default remote caching provider. If you want to link your local turborepo to your Remote Cache you can authenticate the Turborepo CLI with your Vercel account:

turbo login

Then, link your turborepo to your remote cache:

turbo link

Once enabled, make some changes to a package or application you are currently caching and run tasks against it with turbo run. Your cache artifacts will now be stored locally and in your Remote Cache. To verify that this worked, delete your local Turborepo cache:

rm -rf ./node_modules/.cache/turbo

Run the same build again. If things are working properly, turbo should not execute tasks locally, but rather download both the logs and artifacts from your Remote Cache and replay them back to you.

turbo login --sso-team=<team-slug>

Next Steps

You're now up and running with Turborepo, but there are still a few things to do:

• Understand how Turborepo caching works
• Correctly handle environment variables
• Learn to orchestrate task running with pipelines
• Efficiently filter package tasks
• Configure Turborepo with your CI provider