How to deploy a monorepo to Netlify

Introduction

Monorepos have become a popular way to manage multiple applications and packages in a single repository. Tools like Turborepo, Nx, and pnpm workspaces make it easier than ever to share code and keep everything in sync.

Netlify fully supports monorepos, but the setup is slightly different compared to deploying a single app repository. In this guide, you’ll learn how to deploy a monorepo to Netlify in a clean, reliable way.

What Netlify needs to build your site

At build time, Netlify needs three things:

• The base directory where your app lives
• The build command to run
• The publish directory that contains the final static output

In a monorepo, these values usually live in a subfolder instead of the repository root.

Example monorepo structure

Here’s a common setup:

.
├── apps
│   ├── web
│   │   ├── package.json
│   │   └── dist
│   └── admin
├── packages
│   └── ui
├── package.json
└── pnpm-workspace.yaml

Let’s assume you want to deploy apps/web.

Configuring the site in Netlify

You can configure your monorepo deployment either in the Netlify UI or using a netlify.toml file. Using a config file is recommended, especially when you have multiple sites.

Using netlify.toml

Create a netlify.toml file in the repository root:

[build]
base = "apps/web"
command = "npm run build"
publish = "dist"

This tells Netlify to:

• Move into apps/web
• Run the build command there
• Deploy the contents of apps/web/dist

Environment variables and monorepos

Environment variables work exactly the same in monorepos as in single-app repos.

Define them in:

• Site settings → Environment variables
• Or via the Netlify CLI

They will be available to the build process inside the base directory.

Deploying multiple apps from one monorepo

A common pattern is deploying multiple Netlify sites from the same repository.

Example:

• apps/web → production site
• apps/admin → internal dashboard

Each Netlify site points to the same Git repository but uses a different base directory and build configuration.

Working with Turborepo or Nx

If you’re using Turborepo or Nx, your build command might look like this:

npx turbo run build --filter=web

Or for Nx:

npx nx build web

Set this as the build command in netlify.toml or the Netlify UI, and keep the base directory at the repo root if required by your tooling.

Caching and build performance

Netlify automatically caches dependencies between builds. For monorepos, this can significantly reduce build times, especially when combined with Turborepo or Nx caching.

No extra configuration is needed in most cases.

Common pitfalls

A few things to double-check if builds fail:

• The publish directory is relative to the base directory
• The build command runs successfully locally
• The correct Node version is configured if required
• Your workspace package manager is supported (npm, pnpm, yarn)

Conclusion

Deploying a monorepo to Netlify is mostly about telling Netlify where your app lives and how to build it. Once configured, monorepos work just as smoothly as single-app repositories.

This setup scales well as your project grows and makes it easy to deploy multiple sites from a single codebase.