Monorepos allow you to manage multiple projects in a single directory. They are a great way to organize your projects and make them easier to work with.

Using Monorepos with Vercel dashboard

From within your personal or Team account, use the "New Project" button to import your monorepo project.

If you'd like to deploy multiple different directories within the same Git repository, you can do so by creating a separate Project for each directory and configuring the Root Directory setting for it.

The easiest way to achieve this is by importing your Git repository multiple times and selecting a different Root Directory every time – until one Project was created for each of the relevant directories.

Selecting a Root Directory for one of your new Projects.

Once you've created a separate Project for each of the directories within your Git repository, every commit will issue a Deployment for all connected Projects and display the resulting URLs on your pull requests and commits:

An example of Deployment URLs provided for a Deployment via Git.

The amount of Vercel Projects that can be connected with the same Git repository is limited depending on your plan. To increase this limit, please contact our Sales Team.

Using Monorepos with Vercel CLI

Vercel CLI should always be invoked from the monorepo root, not the subdirectory.

First, run vercel link to select the Vercel Project (you can only link to one at a time). Once linked, subsequent commands such as vercel dev will use the selected Vercel Project. To switch to a different Project in the same monorepo, run vercel link again and select the new Project.

Alternatively, you can use git clone to create multiple copies of your monorepo in different directories and link each one to a different Vercel Project.

Note: Check out this example of a monorepo with Yarn Workspaces.

Ignoring the Build Step

Pushing a commit to your monorepo will create a Deployment for each of the connected Vercel projects.

If you want to abort the Build Step for certain projects if their files didn't change, you can do so with the Ignored Build Step project setting.

Note: Check out this Support Article for further examples and information.

Turborepo

Turborepo is a build system for JavaScript/TypeScript projects, that gives you:

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

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

Setup Turborepo

To begin using Turborepo, follow the Getting Started guide for adding Turborepo to your monorepo Project, configured your Pipelines, and logged in with your Vercel account.

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

Step 0: Ensure you are caching environment variables (and files outside of packages and apps) correctly

Toolchains like Next.js and Create React App 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, this could result in shipping environment variables from a cached build to the wrong environment.

Note: If you are deploying the starter Turborepo project, there are no environment variables to worry about. However, you should to be aware of this behavior as you continue to use Turborepo.

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_`)

Here's an annotated example of a Turborepo configuration, that handles all of the above:

{
  "$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.

Step 1: Import your project

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

Step 2: Set the Build Command

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 --filter=<app>...

Setting the Turborepo build command.

Step 3: Set the Root Directory

Set the Root Directory, 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:

- apps
  - docs
    package.json
- packages
  - ui
    package.json

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

The root directory where the runnable code lives.

Step 3.5: Optional settings if using npm workspaces

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.

Step 4: Link your project

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 (Beta) is enabled by default on Vercel (for organizations with Turborepo enabled), meaning artifacts are shared across all projects in an organisation or account. This powerful feature enables you to share completed computations with your team and CI/CD pipelines.

To explore the full power of Turborepos Remote Caching capabilities, you will need a Team setup on any plan (though a Personal Account will also be able to share the cached artifacts).

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

Step 5: Test the caching

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.

Learn more about Turborepo and its many features.

Monorepo FAQ


Whether or not your deployments are queued depends on the amount of Concurrent Builds you have available. Personal accounts are limited to 1 Concurrent Build, while teams can customize the amount on the "Billing" page in the team settings.

Learn more about how to adjust your Concurrent Builds here.

After having set up your monorepo as described above, each of the directories will be a separate Vercel project, and therefore be available on a separate domain.

If you'd like to host multiple projects under a single domain, you can create a new project, assign the domain in the project settings, and proxy requests to the other upstream projects. The proxy can be implemented using a `vercel.json` file with the rewrites property, where each `source` is the path under the main domain and each `destination` is the upstream project domain.

Pushing a commit to a Git repository that is connected with multiple Vercel projects will result in multiple deployments being created and built in parallel for each.

To access source files outside the Root Directory (which enables Yarn & Lerna Workspaces), enable the "Include source files outside of the Root Directory in the Build Step" option in the Root Directory section within the project settings.

Vercel projects created after August 27th 2020 23:50 UTC have this option enabled by default.

If you're using Vercel CLI, at least version 20.1.0 is required.

Vercel CLI should always be invoked from the monorepo root, not the subdirectory.

First, run vercel link to select the Vercel Project (you can only link to one at a time). Once linked, subsequent commands such as vercel dev will use the selected Vercel Project.

To switch to a different Project in the same monorepo, run vercel link again and select the new Project.

Alternatively, you can use git clone to create multiple copies of your monorepo in different directories and link each one to a different Vercel Project.

Note: Use Vercel CLI 20.1.0 or newer to ensure you can take advantage of the option for accessing source files outside the Root Directory (mentioned in a section above).

Vercel CLI will accept Environment Variables instead of Project Linking, which can be useful for deployments from CI providers. For example:

VERCEL_ORG_ID=team_123 VERCEL_PROJECT_ID=prj_456 vercel

Learn more about Vercel CLI for custom workflows.

Yes. Turborepo is available on all plans.