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 will inline build time environment variables (e.g. NEXT_PUBLIC_XXX) in bundled outputs as strings. If you do not declare these variables in your Turborepo configuration, it could result in shipping environment variables from a cached build to the wrong environment.

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:

  • Including environment variables in a dependsOn in your pipeline definition prefixed by a $ will impact the cache fingerprint on a per-task or per-package-task basis
  • Including environment variables in globalDependencies list prefixed by a $ will impact the cache fingerprint of all tasks
  • Including files or globs of files in globalDependencies will impact the cache fingerprint of all tasks. This is not related to environment variables, but useful for files in the root of your monorepo that could impact multiple packages or applications (e.g. .eslintrc or tsconfig.json). If you are deploying the default Turborepo starter, there are no such files
  • The value of any environment variable that includes THASH in its name will impact the cache fingerprint of all tasks
Note: Next.js applications should consider declaring all client-side environment variables (i.e. those that are prefixed with `NEXT_PUBLIC_`)

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

{
  "$schema": "https://turborepo.org/schema.json",
  "pipeline": {
    "build": {
      "dependsOn": [
        "^build",
        // 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",
        "$NEXT_PUBLIC_STRIPE_PUBLIC_KEY",
        "$NEXT_PUBLIC_ANALYTICS_ID"
      ],
      "outputs": [".next/**"]
    },
    "docs#build": {
      // override settings for the "build" task for the "docs" app
      "dependsOn": [
        "^build",
        "$NEXT_PUBLIC_STRIPE_PUBLIC_KEY",
        "$NEXT_PUBLIC_ANALYTICS_ID"
      ],
      "outputs": [".next/**"]
    }
  },
  "baseBranch": "origin/main",
  "globalDependencies": [
    "$GITHUB_TOKEN", // env var that will impact the hashes of all tasks,
    "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. Whenever 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 set the Framework to Next.js (or whatever your application is using) and then 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.

(Make sure to run turbo from the root directory)

  cd ../.. && npx turbo run build --scope=<app> --include-dependencies --no-deps

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.

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.