How to Deploy Multiple Repositories to Subfolders Under One Website with Netlify

As a web developer, you may find yourself working on a project that involves multiple related repositories that need to be deployed under a single domain. For example, you might have a main website, a documentation site, a blog, and an ecommerce store that are all part of the same overarching project.

Deploying each repository to its own separate domain can lead to a fragmented user experience and make maintenance and updates more cumbersome. Ideally, you‘d be able to organize everything under a single domain, with each repository accessible via a different subfolder.

Fortunately, Netlify makes it relatively straightforward to deploy multiple repositories to subfolders under one site. By leveraging Netlify‘s redirect rules, you can map subfolders to different repository deployments, creating a unified website from separate projects.

In this article, we‘ll walk through how to configure Netlify to deploy multiple repositories to subfolders under a single domain. We‘ll cover the key concepts, provide a step-by-step tutorial, and share some tips and best practices along the way.

Why Deploy to Subfolders?

Before we dive into the technical details, let‘s briefly discuss some of the benefits of deploying multiple repositories to subfolders under one site:

Organize related projects in one place: Subfolders provide a logical way to structure multiple related projects under a single umbrella. This is especially useful for larger projects that are broken up across multiple repositories.

Simplify maintenance and updates: With each subfolder mapping to its own repository, you can update and deploy each project independently without affecting the others. At the same time, deploying everything under one domain simplifies DNS management and SSL certification.

Improve SEO with a single domain: Consolidating everything under one domain prevents cannibalization of search rankings that can happen when similar content is spread across different domains. It also contributes to a clearer, simpler user experience.

Now that we understand some of the motivations behind this approach, let‘s take a look at how Netlify handles redirects under the hood.

How Netlify Redirects Work

Netlify offers two primary ways to configure redirect rules for your site: the _redirects file and the netlify.toml file.

The _redirects File

The _redirects file is a plain text file that lives in your site‘s publish directory. Each line in the file specifies a redirect rule. Here‘s an example of what the rules might look like:

/docs/*  https://my-docs-site.netlify.app/:splat  200
/blog/*  https://my-blog-site.netlify.app/:splat  200

Each rule consists of three parts:

1. The source path to match (e.g. /docs/*)
2. The target URL to redirect to (e.g. https://my-docs-site.netlify.app/:splat)
3. The HTTP status code for the redirect (e.g. 200)

The :splat keyword is a special Netlify feature that matches any path segments after the source path and appends them to the target URL.

The netlify.toml File

The netlify.toml file is a configuration file in TOML syntax that lives in the root of your repository. You can use it to specify redirect rules like this:

[[redirects]]
  from = "/docs/*"  
  to = "https://my-docs-site.netlify.app/:splat"
  status = 200
  force = false

[[redirects]]
  from = "/blog/*"
  to = "https://my-blog-site.netlify.app/:splat"
  status = 200
  force = false

The syntax is a bit different but the concepts are the same as the _redirects file. Each [[redirects]] section defines a single redirect rule.

Using the netlify.toml file has a few advantages over the _redirects file:

• It keeps your redirects in version control alongside your site‘s code
• It allows you to specify more advanced configuration options
• It‘s less prone to accidental deletions or overwrites during the build process

For these reasons, we recommend using netlify.toml for specifying redirect rules. However, the _redirects file can still be a good option for simpler setups.

Now that we understand the basics of Netlify redirects, let‘s walk through the process of deploying multiple repositories to subfolders step-by-step.

Step-by-Step Tutorial

For this tutorial, let‘s assume we have three repositories we want to deploy under one domain:

• A main website at the root path /
• A documentation site in the /docs subfolder
• A blog in the /blog subfolder

Here are the steps to get this set up with Netlify:

Step 1: Create a repository for the main site

First, create a new Git repository for your main website. This repository will deploy to the root path / of your domain.

Configure the build settings in Netlify according to your site‘s needs. If you‘re using a static site generator like Gatsby or Hugo, set the build command and publish directory based on the tool‘s conventions.

Step 2: Create repositories for the subfolder sites

Next, create separate Git repositories for each of the subsites that will live in subfolders. In our example, that‘s one repository for the docs site and another for the blog.

Again, configure the build settings in Netlify for each repository based on the tools and conventions you‘re using.

Step 3: Add a netlify.toml file to each repository

In the root of each repository, add a netlify.toml file if you don‘t already have one.

For the main site repository, add the following redirect rules:

[[redirects]]
  from = "/docs/*"
  to = "https://my-docs-site.netlify.app/:splat"
  status = 200
  force = false

[[redirects]]
  from = "/blog/*"  
  to = "https://my-blog-site.netlify.app/:splat"
  status = 200
  force = false

Replace my-docs-site and my-blog-site with the actual Netlify site names for your docs and blog repositories.

These rules tell Netlify to redirect any requests to the /docs or /blog subfolders to the corresponding Netlify deployments for those repositories. The 200 status code means the redirects will happen seamlessly without any visible redirection for the user.

For the docs and blog repositories, you don‘t need to add any special redirect rules to the netlify.toml files. Just configure the build and deploy settings as you normally would.

Step 4: Deploy the sites

Now you‘re ready to deploy all three sites to Netlify.

Trigger a new deploy in each repository either by pushing a new commit or manually initiating a deploy from the Netlify UI.

Once the deploys are finished, you should be able to access your sites at the following URLs:

• Main site: https://your-domain.com/
• Docs site: https://your-domain.com/docs/
• Blog site: https://your-domain.com/blog/

And with that, you‘ve successfully deployed multiple repositories to subfolders under one site! Netlify‘s redirect rules seamlessly map the subfolder paths to the appropriate repository deployments.

Tips and Best Practices

Here are a few tips to keep in mind as you‘re working with Netlify redirects and subfolder deployments:

Avoid redirect loops: Be careful not to create circular redirects where A redirects to B which redirects back to A. This can cause infinite loops and make your site inaccessible.

Use Netlify URLs in redirect rules: As we saw in the tutorial, it‘s best to use the auto-generated Netlify URL (something.netlify.app) in your redirect rules instead of a custom domain. This is more reliable and avoids potential issues with SSL certificates.

Set appropriate status codes: Netlify lets you specify the HTTP status code for each redirect rule. For most subfolder redirects, you‘ll want to use a 200 (Success) to make the redirects invisible to users. Only use a 301 (Permanent Redirect) or 302 (Temporary Redirect) if you actually want to change the URL in the browser‘s address bar.

Test your redirects: Use Netlify‘s Redirect Playground or test your deployed sites thoroughly to make sure your redirects are working as expected. Pay extra attention to edge cases like subpaths, query parameters, and trailing slashes.

Example Use Cases

Before we wrap up, let‘s take a look at a few common use cases for deploying multiple repositories to subfolders:

Documentation site: Deploying a dedicated docs site to a /docs subfolder is a great way to provide in-depth technical documentation alongside your main website or application. You can build the docs with a tool like Docusaurus, Sphinx, or MkDocs and deploy it as a separate Netlify site.

Blog: Many sites maintain a blog in a separate repository to keep it decoupled from the main codebase. Deploying the blog to a /blog subfolder keeps things organized while still providing a unified experience for readers.

Ecommerce store: For JAMstack ecommerce sites, you may want to deploy the main storefront to the root path / and use a /shop subfolder for a headless backend that handles inventory, orders, and fulfillment. This allows you to scale and update the two parts of the site independently.

Landing pages: Marketing sites often involve many landing pages for different campaigns, products, or target audiences. Deploying each landing page as a separate repository to a subfolder like /promo/special-offer or /products/new-launch can make them easier to manage and track.

Limitations and Alternatives

While deploying repositories to subfolders with Netlify is a great solution for many use cases, there are some limitations to be aware of:

Redirect rules can only handle static paths and don‘t support wildcard matching beyond what the :splat keyword allows. For more complex redirect logic, you may need to use Netlify Edge or an external reverse proxy.

Each redirect rule adds a small amount of overhead to the processing of each request. For sites with a large number of redirect rules, it can be more efficient to handle the redirects at the DNS level by deploying each subfolder as a separate subdomain.

In general, subfolders are best suited for static assets and content, while subdomains provide more flexibility for services that need their own backend logic or caching rules.

Conclusion

Deploying multiple repositories to subfolders under one site with Netlify is a powerful way to organize and manage complex projects. By leveraging Netlify‘s redirect rules, you can create a unified experience for users while still keeping the individual parts of your site decoupled and independently scalable.

The key to success with this approach is careful planning and testing of your redirect rules. Make sure to use Netlify URLs, set appropriate status codes, and avoid creating redirect loops. And if you run into limitations with subfolders, consider using subdomains instead.

With these tips and best practices in mind, you‘re well on your way to deploying your own multi-repository sites on Netlify. Happy deploying!