🧠Knowledge Series #32: What’s a monorepo?

Everything you need to know with insights from Figma, Spotify, Airtable and more

🔒The Knowledge Series helps you plug the gaps in your tech knowledge so that you feel more confident when chatting to colleagues. Clearly explained in plain English. One topic at a time. So far, the collection includes APIs, front end development, mobile apps, headless architecture and payments explained - with more topics added every week. 

If you’re a free subscriber and you’d like to upgrade to unlock them you can do so below. Or you can learn more about what you get with paid access here.

---

Hi product people 👋,

Code repos are essentially buckets for storing all of your product’s code, but there are different approaches to storing code which can have a knock on effect on your team’s ability to share components, deal with tech debt and ultimately ship releases to customers.

In this Knowledge Series, we’re going to focus specifically on one of the approaches to code repositories known as mono repositories, or monorepos. 

Using examples from companies like Figma, Airtable, Spotify and others, you’ll understand what monorepos are, how they differ from multi-repos and why they matter to engineers and non-engineers alike so that the next time an engineer talks about potentially migrating to a monorepo, you’ll understand what’s being discussed.

Coming up:

1. What’s a mono repo?

2. The differences between mono repos, code repositories and component libraries

3. Why mono repos exist and the benefits of using them for product teams

4. How companies like Figma, Airtable, Uber, GitHub use monorepos plus examples of companies who don’t use mono repos 

5. How to set up a mono repo in your company and symptoms to look out for

---

The Knowledge Series

What’s a monorepo?

First, let’s start with some simple definitions. Every product’s code is stored in a repository, or repo. 

A code repository is a bit like the file systems we have on desktop operating systems with folders, subfolders and files. In the context of a code repo, a project will include a variety of different things including source code, documentation and other files (we’ll look into this in more detail later).

Without a code repo, it would ultimately be very difficult for engineers to collaborate with each other and most engineering teams will use tools like GitHub, GitLab or BitBucket to host their code.

If you want a deep dive on Git and GitHub, check out one of the previous Knowledge Series on that topic.

OK, so what’s a monorepo?

A monorepo (or monolithic repository) is a single version control repository that contains the code for multiple projects, libraries, or components. This contrasts with the more traditional approach of having separate repositories for each project or application.

In a monorepo, instead of having separate Git repositories for your website, mobile app, backend services, shared libraries, etc., all of that code lives together in one unified codebase.

Companies that use mono repos include:

• Uber

• Airbnb

• Twitter / X

• Google (this is famously one of the largest monorepos in the world)

But, there are also companies who choose not to adopt the monorepo model for various reasons. We’ll look at some real world examples of those companies later.

The anatomy of a mono repo

Essentially, a monorepo is one big Git repository that houses the codebases of companies. 

But they don’t just include code files. Along with code, a monorepo can include a number of various different types of files including shared libraries, configuration files, documentation such as README files, API docs, design docs, testing, tools and more.

Having everything stored in one central location like this is designed to help engineers collaborate and ultimately speed up the time it takes to build thanks to a reduction in duplicate code. Or at least that’s how it’s supposed to work (it has its downsides, too, which we’ll discuss later).

Example

Before we explore how real world companies use monorepos, let’s take a look at 2 mock examples to bring the concept of a monorepo to life.

In the first example, we’ll look at what the structure of a repo with one single project might look like and in the second we’ll look at one which includes multiple projects in one repo (a monorepo).

As we mentioned, repositories are structured as file directories - just like the directories we use on desktops. In this example we have just one project in our repo, myproject which you can see here. The repo contains source code files, test files, documentation, information about the project and other files - but the important takeaway here is that our repo only contains one project.

In companies where multiple teams are working on multiple different projects, each individual repo might have its own separate structure like this:

When multiple teams are working on separate projects like this, we would define the set up as a multi-repo or polyrepo set up.