Best practices for deploying sites from monorepos?


Hi everyone,

I’m using a monorepo model with lerna to manage all the packages we publish on NPM.
Some of those packages are React components or other web-related things where we’d like to publish an ‘example’ on Netlify.

I would prefer to have all configuration handled in code, so we don’t have to go into the Netlify UI every time a new package is added. We could use a netlify.toml file for this, but that seems to come with some limitations:

  • While we can create different ‘contexts’ if I understand correctly, they are always tied to a branch?
  • Things like headers and redirects seem to apply to all contexts

Essentially, a netlify.toml site applies to one ‘site’. What we’re hoping to do is deploy multiple sites from the same repo.
Short of going into the Netlify UI and configuring multiple sites for the same repo, what would be the best way to handle this?

  • Should we deploy from cli rather than use CI?
  • Is there a way to have multiple netlify.toml files in repo subfolders and have them picked up somehow?
  • Some other way?

If anyone has any experience with monorepos hosting multiple sites, or just thoughts or opinions on the matter, I’d be thankful for your feedback.


Hi Joost!

TL;DR Monorepos are a bit hard for us to handle with code-based configuration at present and we are tracking that issue here:

Your statement of the limitations is correct:

  • netlify.toml is read from the root of the repo, so There Can Be Only One which makes for differing configuration of multiple sites to the same repo on the same branches very hard.
  • headers and redirects are not applied to contexts, though there is an only-slightly-convoluted workflow you could use to apply them PER DEPLOY instead, from code - if you construct them at build time into _redirects and _headers instead. Many customers use workflows like this one for doing “conditional” things at build and if your script were a bit smarter (checked something like DEPLOY_URL to discover the netlify sitename - cf if could do this based on which SITE is being built instead.

So to answer your major question: “Short of going into the Netlify UI and configuring multiple sites for the same repo, what would be the best way to handle this?” I have a question - what is the config difference between the sites? If it is a small changeset, we could talk about how you could use the API to reconfigure the sites programatically.

We hope that our CI works for all customers for all use cases, but we know it doesn’t. We are working on a fix to the situation where we COULD read netlify.toml from the base directory you set on a site - but that still doesn’t really help in the way you mention - there would be additional config (of that base parameter) needed in our UI or via API. I’ve attached the URL for this thread to the open ticket for that work so I can ping back in case we ship the implementation of it.


Thanks for the detailed feedback Chris.
I have two one-repo-multiple-sites use-cases:

Multilingual Gatsby

I have a multi-lingual Gatsby site that I’d like to host on language-specific subdomains.
Like this:


For that, I need:

  • To conifgue the GATSBY_LANGUAGE environment variable
  • To configure the correct domain to be deployed on

Apart from that, it’s the same repo, same build command, everything.
(this one is not a mono-repo).

NPM package demo

I also have a mono-repo that holds all the packages we publish on NPM.
Some of these packages have an ‘example’ folder that contains a static example, which I’d like to publish.

For that I need:

  • Multiple build command / file locations
  • Multiple domain names

I can do these things through the UI, and I’m not here to complain :slight_smile:
I’m just trying to see what’s possible in an automated way.


Hi @joostdecock, do you want all of those subdomains to load from a single Netlify site, or is your intention to have them each on different Netlify sites? If I were you, I’d set them up as separate Netlify sites that are all linked to the same repo. You can then set different environment variables on each of the netlify sites, as well as different domains.

1 Like

I agree with you, different sites makes the most sense.

What I was hoping however was to have a way to handle this in code (through the API) rather than having to go into the UI and create those sites manually.

But, it’s not the end of the world. As I said, I know it can be done through the API, I was just curious about my options for automation.

1 Like