Monorepos
Netlify provides flexibility in how you organize and build a site or application. Although some sites are built directly from the root of a repository, we also support those with a more complex setup like monorepos — repositories that contain multiple sites or apps, each in its own subdirectory.
To help you successfully configure sites from a monorepo, Netlify offers both automatic monorepo detection and manual configuration options. You also have the ability to control the volume of commit status notifications and to configure a custom ignore command. This document also outlines our recommended monorepo setup.
Using the CLI with a monorepo?
After you set up your site on Netlify, you can use the Netlify CLI’s --filter flag to specify which site in your monorepo to run commands on. This way, you can work directly from the root of your project. Learn more about using the CLI with monorepos.
# Definitions
To deploy a site from a monorepo, you may need to set or use the following:
Base directory: directory where Netlify checks for dependency management files such as
package.jsonor.nvmrc, installs dependencies, and runs your build command. The build system will use this directory to perform caching during the build process. If not set, the base directory defaults to the root of the repository.Site files: source files in your repository that represent the code for your site and any related configurations. Also known as your site’s package.
Package directory: typically used for monorepos, the directory that contains your site files, including the
netlify.toml. Set this only if the location is different from the base directory. Learn more about how Netlify searches for your configuration files in monorepos.Build command: the command to run to build your site if you are using a static site generator or other build tool. For example,
npm run build. The build command runs in the Bash shell, allowing you to add Bash-compatible syntax to the command. Visit the frameworks doc to learn about typical build commands for popular tools.Publish directory: directory that contains the deploy-ready HTML files and assets generated by the build. The directory is relative to the base directory, which is root by default (
/). Visit the frameworks doc to learn about typical publish directories for popular tools.Only files in the publish directory are deployed
Files and assets located outside of the publish directory won’t be included in site deploys.
Netlify configuration file: optional configuration file (
netlify.toml) that specifies how Netlify builds and deploys your site — including redirects, branch and context-specific settings, and more. Learn more about file-based configuration.
# Automatic monorepo detection
When you create a new site from an existing repository, Netlify automatically scans the repository to detect if you are using a monorepo.
If Netlify detects multiple sites in your repository, the Netlify UI displays a list of the sites and directories for you to select under Site to deploy.
Once you select a site to deploy, Netlify automatically fills in the Build command and Publish directory based on that selection.
Netlify also uses this selection to set the Package directory, and leaves the Base directory unset. You can review both fields under
after you finish setting up your site. As the Base directory is not set, Netlify uses the root of the repository as the default to install dependencies and build your site.
If the site you wish to deploy isn’t automatically detected, select Other (configure manually) in the list and you can manually configure the site instead.
# Manual configuration
If your site isn’t automatically detected, Netlify offers you the option to manually set the base directory, package directory, build command, and publish directory for your site. While there are multiple ways to set each of these values, the recommended method may differ depending on your project setup.
# Set the base directory
Want to run builds for your monorepo in root?
To install dependencies and run builds in the root directory of your monorepo, you don’t need to set the base directory. Netlify uses the root of the repository as the default. If your Netlify configuration file is located with your project in a directory other than root, you can specify the location with a package directory.
If not explicitly set, the base directory defaults to the root of the repository. If you want to install dependencies and build your site in a subdirectory rather than root, you can specify this by setting a base directory.
For example, if your repository has a monorepo workspace set up in a /frontend directory and other unrelated code in a /backend directory, you likely want to set your base directory to /frontend instead of root (/).
You can set a base directory in the following ways:
- in the Netlify UI, when you select Add new site. For an existing site, you can update the setting at .
- in a Netlify configuration file stored at the root of your repository. Use the
baseproperty under[build]settings, and Netlify will use that value to set the base directory when you first set up the site. - if you’re creating a Deploy to Netlify button for other people to easily clone and deploy your site, use the
basequery parameter to set the base directory for that button. You can create different buttons for each site in your monorepo by setting a differentbasevalue for each button.
A base directory specified in a root-level netlify.toml overrides the UI setting.
# Set the package directory
If you use a monorepo and store your site files in a different directory from your base directory, you can specify the location using the Package directory field in the Netlify UI.
This is helpful if you want to install dependencies and run builds in the root but want to store your site’s source files, including the corresponding netlify.toml, in separate project directories. If you don’t set this value, Netlify will search for the netlify.toml in the base and root directories.
In addition, if you don’t set an explicit publish directory, Netlify uses the package directory to search for the directory that contains the output of your build (for example, a dist folder) and any related _headers and _redirects files within that directory.
To set the package directory for a site:
- Navigate to .
- Select Configure.
- Enter the Package directory. For example,
/packages/website. - Select Save.
# Set the build command
You can manually set the build command in the following ways:
- in the Netlify UI, when you select Add new site. For an existing site, you can update the setting at .
- in a Netlify configuration file. Use the
commandproperty under[build]settings. Learn more about file-based configuration. - using Netlify CLI when setting up continuous deployment for a site.
To find the typical build command for your framework, refer to the frameworks doc.
# Set the publish directory
You can manually set the publish directory in the following ways:
- in the Netlify UI, when you select Add new site. For an existing site, you can update the setting at .
- in a Netlify configuration file. Use the
publishproperty under[build]settings. Learn more about file-based configuration. - using Netlify CLI when setting up continuous deployment for a site.
To find the typical publish directory for your framework, refer to the frameworks doc.
# Use a Netlify configuration file
You can configure most build and deploy settings for your site using a Netlify configuration file instead of the Netlify UI. Note that the package directory can only be set in the Netlify UI.
Depending on your monorepo project setup, you may have one or more Netlify configuration files in your repository. The best practice is to have one Netlify configuration file for each site, where the settings in each file are unique to that site. Settings in a root configuration will apply to all sites in your monorepo.
Netlify needs to know which files to use for your site build. You can either explicitly set the location of the site’s configuration files or rely on Netlify to find it in either your base or root directory.
For a sample netlify.toml file, refer to the file-based configuration docs. For an example monorepo file structure that includes a different configuration file for each site, refer to the recommended monorepo setup section below.
Use absolute file paths in the netlify.toml
To specify the location of plugins, functions, or other configuration details in netlify.toml for a site in your monorepo, use absolute paths that are relative to the base directory. If not set, the default value for the base directory is the root (/).
For example, if the site’s base directory is /frontend, the site’s package directory is /frontend/packages, and the plugin is within /frontend/packages/my-app/plugins, the configuration file should specify the plugin location as /packages/my-app/plugins/netlify-plugin-check-output-for-puppy-references.
# How Netlify finds your configuration files
Netlify will search for configuration files in the following order:
- Package directory
- Base directory
- Root directory
# Commit status notifications
You can manage the amount of commit status and commit check notifications for projects where one repository builds multiple applications. These types of deploy notifications are available on commit lists and pull/merge requests for Netlify sites connected to GitHub or GitLab and are also referenced as Commit status webhooks.
For your Netlify team, go to
and select Edit commit status webhooks.Choose one of the following options:
- Multiple webhooks per repo: enables commit statuses and commit checks for multiple sites linked to a repository.
- One webhook per repo: limits commit checks and commit statuses in a pull/merge request or commit list to one linked site only, regardless of the number of sites linked to a repository.
# Recommended monorepo setup
Whether you want to build a single site from a monorepo or multiple sites from a monorepo, the recommendations are the same:
Set the subdirectory that contains the site you want to deploy as your package directory. If you have custom configuration settings for the site in a
netlify.toml, ensure the file is in the same directory.Leave the base directory as the default, the repository root (
/).Define all dependencies at a more specific, subdirectory level, and leave dependency management up to the tool you’re using.
For example, if you have a monorepo with a site that uses React and a component library that also uses React, you should list
reactas a dependency inpackage.jsonfiles within each subdirectory. With a Yarn workspace, for example, Yarn can hoist dependencies dynamically, moving them to the root of the repository whenever it makes sense to do so.
# Example monorepo setup
Here’s an example directory structure for a monorepo that contains a component library and two sites to be hosted on Netlify:
/
├─ apps/
│ ├─ app-1/
│ │ ├─ package.json
│ │ ├─ netlify.toml
│ │ ├─ ...app-1-source-files
│ ├─ app-2/
│ │ ├─ package.json
│ │ ├─ netlify.toml
│ │ ├─ ...app-2-source-files
│
├─ other-packages/
│ ├─ component-library/
│ │ ├─ package.json
│ │ ├─ ...component-library-source-files
│
├─ package.json
There is a subdirectory for each site that contains the source files for that site and a netlify.toml with site-specific configurations. All necessary site dependencies are declared in package.json files within each subdirectory, and the root-level package.json is used to define a Yarn or npm workspace.
In this example scenario, you would create two separate Netlify sites linked to the monorepo. If Netlify automatically detects that you are using a monorepo during the set-up step for each site, you can select the directory to deploy in the Netlify UI and Netlify will configure the build settings for you.
If you need to configure the sites manually, you can use the Netlify UI to set the package directory for each site to point to the site’s subdirectory within the monorepo. Leave the base directory unset for Netlify to use the repository root as the default value.
For example, the package directory for the app-1 site should be apps/app-1 and the base directory should be unset. Based on this configuration, Netlify will access the site’s source files and configuration files from apps/app-1 and will run the dependency installation and build command in the repository’s root (/).
By default, any changes in the base directory (the repository root, by default) trigger a build of all connected sites. If you would like to only trigger site builds when a change occurs in the site’s subdirectory, you can add a custom ignore builds command to the site’s netlify.toml file.
No special configuration required if you declare dependencies at both the root and subdirectory level
Most package managers, such as Yarn and npm, are context-aware now. This means that they can run in the root directory and manage dependencies declared in subdirectories as needed. In addition, Netlify’s build system caches all node_modules directories within the repository, regardless of where the dependencies are declared.
# More build configuration resources
Did you find this doc useful?
Your feedback helps us improve our docs.