Using Monorepos
Vercel provides support for monorepos. Learn how to deploy a monorepo here.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.
- Go to the Vercel Dashboard and ensure your team is selected from the scope selector.
- 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.
- From the Import Git Repository section, select the Import button next to the repository you want to import.
- 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:
- Configure any necessary settings and click the Deploy button to deploy that project.
- 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.
You should use Vercel CLI 20.1.0 or newer.
- Ensure you're in the root directory of your monorepo. Vercel CLI should not be invoked from the subdirectory.
- Run
vercel link
to link multiple Vercel projects at once. To learn more, see the CLI documentation:Terminalvercel link --repo
- Once linked, subsequent commands such as
vercel dev
will use the selected Vercel Project. To switch to a different Project in the same monorepo, runvercel 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.
See this example of a monorepo with Yarn Workspaces.
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.
This feature is only available for projects connected to GitHub repositories
and those using npm
, yarn
, or pnpm
workspaces. See
requirements for more information.
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:
- From the Dashboard, select the project you want to configure and navigate to the Settings tab.
- Go to the General page of your Project Settings.
- Scroll down to Root Directory
- Toggle the Skip deployment switch to Enabled.
- 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
, orpnpm
workspaces. We detect your package manager by the lockfile present at the repository root. You can also specify the package manager with thepackageManager
field in rootpackage.json
file. - All packages within the workspace must have a unique
name
field in theirpackage.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 thepackage.json
ofpackage-e2e
.
- For example, an end-to-end tests package (
Was this helpful?