Multiple netlify.toml files in monorepo

I’m struggling to understand the new monorepo support from only the blog post and brief paragraph in the docs.

One fundamental question I have is: does this mean we can drop different netlify.toml files in our monorepo package subdirs? The blog post doesn’t mention this, or really any other technical specifics.

The paragraph in the docs says you can configure your base dir in the netlify.toml file. But if the base dir is specified in the netlify.toml that seems to me to require that the netlify.toml file is in the monorepo root.

So I assumed that we’d still have to configure the base dir in the Netlify UI, so that the build process knew where to find the correct netlify.toml file (that is, in the monorepo package subdir).

Am I just misunderstanding this? Does the new monorepo support not permit a netlify.toml file in each website subdir? The folks in this thread seem to think it does support multiple netlify.toml files… :thinking:

It would be fantastic if the docs specifically addressed this issue, it seems fairly core to understanding the feature.

Thanks so much for working on monorepo support – that’s hugely important for us and it’s great to know it’s on your radar. Would love to see some work on the remaining issues with monorepos built with yarn workspaces worked out as well.


I’ve confirmed that the monorepo support does in fact support multiple netlify.toml files. I also tested what would happen if you put a netlify.toml in the monorepo root and then also one in the site package subdir. I was hoping Netlify would merge the two config files, preferring the subdir one in case of duplication, but in fact, it seems to totally ignore the monorepo root one and only find or care about the one in the base directory (sub-package).

The docs around this are still pretty small and somewhat misleading. For instance they reference setting your base directory in the netlify toml – but if you’re trying to use the new monorepo support, you can’t do that – you have to set the base dir in the UI so that Netlify will go there and find the netlify.toml there and give you the benefit of skipping publishing when the subdir doesn’t change.

1 Like

You should be able to put the netlify.toml in each subdir, if the base is configured in the UI, yes.

If you have one in the root that doesn’t have base set, that should be fine. If base is set it in, and doesn’t match what’s in the UI, not sure what would happen (so, don’t set base in that netlify.toml unless you have only one netlify site, is my suggestion).

Does that help?

I will also review this feedback with our documentation team who are working specifically on the monorepo docs this sprint.

Hmm so you have monorepo, where you have folder with different sites, and you can put there different netlify.toml files, and it is working ? It is working for me, if i will set root of my deployment to that packages, but if root will be the whole repository, than it is picking up only netlify.toml in root of the whole repo :confused:

If i set base in UI to the root of monorepo repository, is it still possible to have other netlify.toml files in my subdirs ?

In my case, I need to have access to the whole monorepo while building and deploying (i have to build shared-components monorepo package locally, cause i don’t want to publish them to npm). So i need to run scripts from root package.json.

Right now, i see that i can have multiple netlify.toml files, but for any deployment i need to set base, to the folder where this specific netlify.toml sits.

I believe that should be possible. Here’s what I’d try:

  • set the base ONLY in the UI, for every site except the one that builds from root
  • set NO base in the UI on the site that builds from root
  • never set base in any toml file.

Please let me know if that doesn’t work!

1 Like

Hey @fool,

I’m also having trouble with this. I have a lerna monorepo with multiple packages nested inside a subdirectory. Here’s a basic example of the monorepo:


The website1 package needs to be deployed independently of website2. Both website1 and website2 have components as a dependency.

Currently if I try and build website1 in netlify with base set to packages/website1 in the UI, the build will fail because it can’t find the components dependency - it’s a local package within the monorepo and not published to npm. Same goes for website2.

The current alternative is to not set the base, which runs build commands from the root directory and finds all dependencies without a problem, but this will trigger build for both website1 and website2. I’ve tried adding a netlify.toml file to each package with an ignore field but since I’m building from the root directory it’s not picking that up. I have also tried deploying on Gatsby Cloud using /packages/website1 as the base directory and it installs local dependencies without a problem which tells me it’s achievable, just wondering if I’m missing something.

Any help or clarification would be much appreciated :slight_smile:

1 Like

Hi, @groovy, which package.json handles the dependency install for packages/components?

I’m asking because I think making the base directory packages/website1 will work but you’ll need an extra step in the build command to do the dependency install for the components manually like so:


cd ../components ; npm install ; cd ../website1 ; npm run build

Note, I don’t know much about lerna. Do you still use npm for dependency installs with lerna?

​Please let us know if there are other questions. Even if there are no other questions, we’d still love to hear about the solution if you find it.

I have a similar situation with a monorepo using Lerna/Workspaces. My structure is something like this:

├─── components
├─── utils
├─── gatsby-theme
└─── test-site
     ├─── package.json
     ├─── netlify.toml
     └─── public
          └─── (site published from here)

The root package.json contains the build script I need to use, which runs lerna run build --stream. The site I’m needing to deploy is packages/test-site, which relies on having the other 3 packages built out locally.

It seems I have a catch-22. Setting my base to packages/test-site (via the UI) results in failure to resolve the other monorepo packages since they haven’t been built. Setting the base to the root builds all packages successfully but seems to result in the netlify.toml file not being found (I assume this is the case because none of my redirect rules seem to have processed). I guess it’s only looking for netlify.toml in the root since that is what’s specified as the base directory.

Any ideas for what my options could be? I suppose I could try copying netlify.toml to the root level at some point during the build process, though that wouldn’t be ideal…

––– UPDATE –––

Following the thought process of my previous reply, I was able to straighten out my situation and get the deploy fully working by copying the netlify.toml file to the monorepo root during build.

I’m using run-s from npm-run-all to have Lerna build all packages first and then copy packages/test-site/netlify.toml to the root.

In root package.json:

"scripts": {
    "build": "lerna run build --stream",
    "copy-netlify-toml": "cp packages/test-site/netlify.toml netlify.toml",
    "build:test-site-deploy": "run-s build copy-netlify-toml"

Then in the UI, I use build:test-site-deploy as the build command, no base set, and packages/test-site/public still as the publish directory.

Of course, one thing to keep in mind is that this really only works when the redirects & headers are all you intend to use the netlify.toml file for (which is true in my specific case). I believe all other configs only have an effect if netlify.toml already exists in its proper place at the very start of the deploy before the build command is executed, so I suppose a build plugin might be what you’d need if you want to use the file for other settings.

Hopefully this helps somebody in some way…Lol.


Thanks for the reply @luke. I forgot to mention I’m using yarn workspaces with Lerna. I was able to successfully deploy with base set to packages/website1 and adding an empty yarn.lock file at the website1 root. I found the workaround in this github issue. Interestingly the original poster jaredh159 already referenced this issue in relation to multiple toml files but I missed the lerna.lock trick in there.