Using Monorepos

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.

Get started with monorepos on Vercel in a few minutes by using one of our monorepo quickstart templates.

Turborepo

Read the Turborepo docs, or start from an example.

DeployLive Example

Nx

Read the Nx docs, or start from an example.

DeployLive Example

1. Go to the Vercel Dashboard and ensure your team is selected from the scope selector.
2. Select the Add New… button, and then choose Project from the list. You'll create a new project for each directory in your monorepo that you wish to import.
3. From the Import Git Repository section, select the Import button next to the repository you want to import.
4. Before you deploy, you'll need to specify the directory within your monorepo that you want to deploy. Click the Edit button next to the Root Directory setting to select the directory, or project, you want to deploy. This will configure the root directory of each project to its relevant directory in the repository:

   

5. Configure any necessary settings and click the Deploy button to deploy that project.
6. Repeat steps 2-5 to import each directory from your monorepo that you want to deploy.

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:

The number of Vercel Projects connected with the same Git repository is limited depending on your plan.

1. Ensure you're in the root directory of your monorepo. Vercel CLI should not be invoked from the subdirectory.
2. Run vercel link to link multiple Vercel projects at once. To learn more, see the CLI documentation:
   Terminal

   vercel link --repo

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

By default, pushing a commit to your monorepo will create a deployment for each of the connected Vercel projects. However, you can choose to:

• Ignore the build step for projects whose files have not changed.
• Skip unaffected projects by only building projects whose files have changed.

If you want to cancel the Build Step for projects if their files didn't change, you can do so with the Ignored Build Step project setting. Canceled builds initiated using the ignore build step do count towards your deployment and concurrent build limits and so skipping unaffected projects may be a better option for monorepos with many projects.

If you have created a script to ignore the build step, you can skip the the script when redeploying or promoting your app to production. This can be done through the dashboard when you click on the Redeploy button, and unchecking the Use project's Ignore Build Step checkbox.

When you use Turborepo, you can intelligently cancel builds using turbo-ignore.

You can enable this option to detect which projects are affected by a commit and Vercel will only build those projects. To skip unaffected projects:

1. From the Dashboard, select the project you want to configure and navigate to the Settings tab.
2. Go to the General page of your Project Settings.
3. Scroll down to Root Directory
4. Toggle the Skip deployment switch to Enabled.
5. Click Save to apply the changes.

This setting does not occupy any concurrent build slots, unlike the Ignored Build Step feature. This means reducing the number of queued builds by automatically skipping projects that don't need to build.

• This feature is only available for projects connected to GitHub repositories.
• The monorepo must be using npm, yarn, or pnpm workspaces. We detect your package manager by the lockfile present at the repository root. You can also specify the package manager with the packageManager field in root package.json file.
• All packages within the workspace must have a unique name field in their package.json file.
• Dependencies between packages in the monorepo must be explicitly stated in each package's package.json file. This is necessary to determine the dependency graph between packages.
  • For example, an end-to-end tests package (package-e2e) tests must depend on the package it tests (package-core) in the package.json of package-e2e.