Skip to content

Turborepo is a high-performance build system for JavaScript and TypeScript codebases with:

  • Fast incremental builds
  • Content-aware hashing, meaning only the files you changed will be rebuilt
  • Remote Caching for sharing build caches with your team and CI/CD pipelines

And much more! Read the "Why Turborepo" docs to learn about the benefits of using Turborepo to manage your monorepos.

To begin using Turborepo, follow the Getting Started guide for adding Turborepo to your monorepo Project, configure your Pipelines, and log in with your Vercel Account.

Once you have completed the initial setup, follow the steps outlined below:

It's important to ensure you are caching environment variables (and files outside of packages and apps) correctly. If you are deploying the starter Turborepo project, there are no environment variables to worry about. However, you should to be aware of shipping environment variables as you continue to use Turborepo.

Frameworks like Next.js inline build-time environment variables (e.g. NEXT_PUBLIC_XXX) in bundled outputs as strings. Turborepo will automatically try to infer these based on the framework, but if your build inlines other environment variables, or otherwise affects the build output, you must declare them in your Turborepo configuration.

You can control Turborepo's cache behavior (hashing) based on the values of both environment variables and the contents of files in a few ways. Read the [Caching docs on Turborepo for more](https://turborepo.org/docs/core-concepts/caching!

The following example shows a Turborepo configuration, that handles these suggestions:

{
  "$schema": "https://turborepo.org/schema.json",
  "pipeline": {
    "build": {
      "dependsOn": [
        "^build",
      ],
      "env": [
        // env vars will impact hashes of all "build" tasks
        "SOME_ENV_VAR",
      ],
      "outputs": ["dist/**"]
    },
    "web#build": {
      // override settings for the "build" task for the "web" app
      "dependsOn": [
        "^build",
      ],
      "env": [
        "SOME_OTHER_ENV_VAR"
      ]
      "outputs": [".next/**"]
    },
  },
  "globalEnv": [
    "GITHUB_TOKEN", // env var that will impact the hashes of all tasks,
  ],
  "globalDependencies": [
    "tsconfig.json" // file contents will impact the hashes of all tasks,
  ]
}
Note: In most monorepos, you don't often use environment variables in shared packages, but mostly only in applications. To get higher cache hit rates, you should likely only include environment variables in the app-specific tasks where they are used/inlined.

Once you've declared your environment variables, commit and push any changes you've made. When you update or add new inlined build-time environment variables, be sure to declare them in your Turborepo configuration.

Create a new Project on the Vercel dashboard and import your monorepo project.

From the Settings panel:

  1. Set the Framework to Next.js (or the framework your application is using)
  2. Set the Build Command, where <app> is the name field of the target application's package.json (e.g. docs or web if you're using a starter project), and save your changes.
cd ../.. && npx turbo run build --filter=<app>...

Setting the Turborepo build command.

Set the Root Directory to tell Vercel which directory within your project contains your code. This can be set in your project's Settings, under the General tab.

The root directory where the runnable code lives.

Turborepo convention places applications in the /apps directory (with any other packages in /packages), this means that if your project directory had the following structure:

You would set your root directory to apps/docs. Once set, save your changes.

If your project is using npm workspaces you will need to tell npm to install node_modules in the correct directory by setting the Install Command to npm install --prefix=../path/to/workspaces/root where /path/to/workspaces/root is the relative path to the root of your monorepo (the directory where you’ve defined the workspaces key in package.json) from the Root Directory (where the Install Command is executed).

If you are deploying an application from one of the Turborepo starters/examples (e.g. apps/docs or apps/web), you can set your Install Command to npm install --prefix=../..

Note: This is only required if using npm workspaces, and doesn't apply when using pnpm or yarn workspaces.

Setting the install command when using npm workspaces.

Turborepo can automatically detect if your project or one of its dependencies has changed and needs to be built and deployed.

To configure this, set the Ignored Build Step to use turbo-ignore:

npx turbo-ignore

To connect to your Vercel Remote Cache from your local machine, from the root of your project, authenticate with the Turborepo CLI:

  npx turbo login

Then link your project and connect to the Remote Cache:

  npx turbo link

Remote Caching is enabled by default on Vercel for organizations with Turborepo enabled, allowing you to share artifacts and completed computations with your team and CI/CD pipelines.

Next, cd into each project and run vercel link to link each directory within the monorepo to your Vercel Project.

Your project now has the Remote Cache linked. Run turbo run build to see the caching in action. Turborepo caches the filesystem output both locally and remote (cloud). To see the cached artifacts open node_modules/.cache/turbo.

Now try making a change in a file and running turbo run build again. The builds speed will have dramatically improved. This is because Turborepo will only rebuild the changed files.