Monorepo. One Repo To Rule Them All.

You start having more applications as your system grows. Even if you started with something like a mobile app, you’ll need a backend for it as well as an admin portal (which is usually a website). As engineers, we’re taught to modularize our software. This article challenges this principal proposing putting all our apps is a single repository for greater efficiency. Keep on reading to learn how.

What is a monorepo

Imagine you have a mobile app, an admin website, and your backend. Traditionally, each one of these apps lives inside its own code repository. On the other hand, you can have all your apps in a single code repository called the monorepo. This way, all apps are located in a single repo that shares the same changelog.

Monorepo Advantages

As you probably heard Google and Facebook use a monorepo for their projects. There are numerous reasons for it. At the end of the days, it all comes down to efficiency. Managing your code in a single repository is easier than managing it in multiple repositories. Here is an example:

1. Developer Efficiency

If you need to make a change across all three apps in separate repositories, you’ll need to make the following steps:

  1. Make a change in the app.
  2. Create a pull request to review the app code.
  3. Make a change on the backend.
  4. Create a pull request to review your backend code.
  5. Make a change on the website.
  6. Create another pull request to review your web code.
  7. Merge all three.

When you have all apps in a single repository, the need for making different pull requests goes away. This way, you make all changes in one pull request, have your code reviewed once and move on.

2. Simplified Versioning

If your apps are all in different code repositories, each app has to have a different version. Maintaining and matching these versions can be tedious. Monorepo solves this problem by simply having all apps in a single repository.

3. Easier Code Sharing

Monorepo simplifies code sharing which is beneficial to the health of the codebase overall. Shared code is easier to maintain since the change in a shared component propagates to all places that use it. In addition to it, it’s just easier to move things around and extract the code into reusable components in a monorepo. In case of multiple repositories, you need to extract your code into a different repository and create multiple pull requests to use it in separate projects.


How to implement a monorepo in your project

Depending on your technical stack, there are tools out there (like Learna for the Javascript world) which help you to implement the monorepo structure efficiently. That being said, you don’t have to use these tools if you don’t see fit. It is possible to implement monorepo yourself if it’s the best thing to do. Either way, you’ll need to deal with the following things:

1. Continuous Integration

Since all projects are inside a single repository, you now need to determine which project has changed on each code push. If you’re using git, you can see what files are changed with the following command:

$ git diff commitSha1..commitSha2 --name-only

Then you can detect the project name in the diff with the tools like grep. This will help you to determine which project is changed so you can run the build just for this project and/or it’s dependencies. This technique allows you to keep your builds fast instead of re-running all projects on every single change which doesn’t scale well.

2. Deployment

Once you determine which project is changed, you can deploy just the projects that changed or the projects that rely on the changed project. Depending on your system, you’ll need to have different jobs dependent on each other. If you use CircleCI, it supports specifying dependencies between jobs out of the box in the version 2.0 using workflows. Other CI/CD systems have similar capabilities.

3. Documentation

Once all your apps are in the same repo, it’s easy to lose track of your documentation. Make sure you maintain the accurate and up to date documentation for each app. It should be crystal clear where the documentation for each app is. This way each developer can get each app up and running quickly and get to implementing features.

Final words

Time and time again I realize that you have to always challenge the status quo. Things move quickly, technologies evolve, so as our users. What worked yesterday is not necessarily what works today. Monorepo is one of the examples of it. Challenging the status quo is how we innovate and build better products. So, go ahead, challenge the way you do things, there is always a better way.