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 get started with Turborepo in your monorepo, follow Turborepo's Quickstart docs.

Follow the steps below to deploy your Turborepo to Vercel:

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 information.

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

turbo.json
{
  "$schema": "https://turbo.build/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, environment variables are usually used in applications rather than in shared packages. To get higher cache hit rates, you should only include environment variables in the app-specific tasks where they are used or 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.

Note: If you haven't already connected your monorepo to Turborepo, you can follow the quickstart on the Turborepo docs to do so.

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

Configuring Project settings during import, with defaults already set.

Vercel handles all aspects of configuring your monorepo, including setting build commands, the Output Directory, the Root Directory, the correct directory for npm workspaces, and the ignored build step.

turbo-ignore determines if a build should continue by analyzing the package dependency graph of the given workspace.

The given workspace is determined by reading the name field in the package.json file located at the current working directory, or by passing in a workspace name as the first argument to turbo-ignore.

Next, it uses turbo run build --dry to determine if the given workspace, or any dependencies of the workspace, have changed since the last successfully deployed commit for the current branch.

Note:

If the branch has not been deployed, turbo-ignore will fall back to comparing against the previous commit. To always deploy the first commit of a new branch, this behavior can be disabled by passing --fallback=false, or customized by providing the ref to compare against (defaults to --fallback=HEAD^).

For more details on turbo-ignore, check out the documentation.

You can optionally choose to connect your Turborepo to the Vercel Remote Cache from your local machine, allowing you to share artifacts and completed computations with your team and CI/CD pipelines.

You do not need to host your project on Vercel to use Vercel Remote Caching. For more information, see the Remote Caching doc.

You can also use a custom remote cache. For more information, see the Turborepo documentation.

First, authenticate with the Turborepo CLI from the root of your monorepo:

terminal
  npx turbo login

Then, use turbo link to link your Turborepo to your remote cache. This command should be run from the root of your monorepo:

terminal
  npx turbo link

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

As a Team owner, you can also enable caching within the Vercel Dashboard.

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.

To see information about the Remote Cache usage, go to the Artifacts section of the Usage tab.