How we handle two projects in a monorepo hosted on one site and one url in Netlify

www.md

Two projects in a monorepo hosted on one site and one url in Netlify

Netlify helps you build your sites or applications in a very easy manner. In most cases, you would have a simple project (e.g. Gatsby) in a repository, that you simply connect via some Git provider. Within a couple of minutes, your site is built and live on a domain.

But some cases are more complex than that. Luckily enough, Netlify supports more advanced setup through their Build & deploy configurations. The purpose of this article is to show you how we hosted two web projects (Gatsby and Docusaurus) from within a monorepo as a single site in Netilfy under the same domain.

Folder structure

It's important to have a look at our folder structure for the monorepo, to understand our build configuration in Netlify.

In our root, we have a folder www, that contains the two projects in question. The structure is as such:

.
├── docs // Docusaurus project
├── reference // Gatsby project
├── build-site.js
├── .gitignore
└── package.json

We want docs to be hosted on https://docs.medusa-commerce.com and reference on https://docs.medusa-commerce.com/api. There is no straightforward way of achieving this.

There are obviously some project specific modifications, that are required. In our case, we exclude the pages/index.js file from the Gatsby project to make it only live on path /api. Additionally, we add our root url, https://docs.medusa-commerce.com, to the Docusaurus url setting making it the root project. These settings vary from application to application, but the approach stay the same.

Building the projects

The standard way for Netlify to build a project is to have a build command specified as part of the configuration. For a Gatsby project, this would almost always be gatsby build. But since we are looking to build two separate applications in one go, we wrote a script.

The script is fairly simple. We simply execute the steps:

1. Install dependencies in both repositories
2. Build the two projects
3. Copy all the built files from the two projects into one folder build in www

As a result, we now have all files gathered in one folder, which is gonna be our Publish directory in Netlify.

Configuring Netlify

The last part of the process is to configure Build & deploy in Netlify. After creating a site with a connection to our monorepo, we need to supply the settings show below:

Base directory: www
Build command: ./build-site.js
Publish directory: www/build

This tells Netlify to run our build script upon deploying the site. It will then use all the built files for the two projects as Publish directory. The last thing we need to do, is to simply deploy the site.

Finally, we can now browse our Documentation as a Docusaurus project at https://docs.medusa-commerce.com and our API reference as a Gatsby project on https://docs.medusa-commerce.com/api.

PS. If you are interested in ecommerce, you should check out our open-source project