Monorepo vs. multi-repo

When starting a new project, it’s common to ask what the best or most appropriate strategy is for managing architecture at the code repository level. One of the biggest challenges that makes answering this question difficult is identifying a solution that meets the needs of the present  yet can still evolve in the future as new scaling, integration and modification needs emerge.

The approach that ends up being selected is not, of course, definitive. There is always the opportunity to adjust according to change, whether that change is internal or external.

Nevertheless, just because you have the option to make a change doesn’t preclude the fact that those changes will inevitably have a cost — trade-offs are always present in software engineering, after all. This means it is extremely important to make the right decision early on, since it will ultimately ensure we are prepared for future challenges.

I have faced these decisions many times throughout my career. In this article I reflect on some of those moments and what I have learned from them: what might I have done differently? Why was one solution right in one context but not another? First, though, let's start from the basics… 

What is a repository?

A repository is the place where all the files of a project are stored, organized and maintained. They contain a change history, giving teams transparency and control over different possible versions.

Nowadays, repositories are commonly used with Git, through providers like Github, GitLab, and Bitbucket. These can store a wide variety of file types.

What is a monorepo?

A monorepo is not a monolith. It’s a software development strategy in which a company's entire codebase is stored in a single repository.

What are the benefits and challenges of using a monorepo?

When deciding whether to use a monorepo it is important to properly evaluate the many trade-offs they involve. Below I’ve highlighted some of the main benefits and challenges.

Benefits

1. Monorepos can help teams to almost instantly start writing clean and maintainable code.

2. They can help with refactoring solutions and documenting flows so when a new member joins the team it’s easy for them to integrate into existing practices.

3. With a monorepo, running automated code tests, whether unit, integration, or end-to-end (e2e) is much easier.

4. If you can select an adequate means of managing your code you can minimize potential chaos in the codebase. A good example of this is using domain-driven design (DDD), so each business domain that works on the code can be easily administered.

5. Because monorepos centralize collaboration, communication within teams should be more effective. Everyone will be clear on the needs and priorities of the team.

6. Monorepos make it easier to manage dependencies by virtue of providing easier access to them.

7. Monorepos support an organizational culture of collaboration and support. When code is shared inside a monorepo, it means the challenges different teams face are also shared, making it easier to solve them together.

Challenges

1. One of the main disadvantages of monorepos is performance. This is because combining code across different functions and contexts in a single repository can slow down code pull operations.

2. If there are several sub-projects in a repository, it’s important to consider that continuous integration (CI) and continuous delivery (CD) type integrations may become a challenge. It’s also useful to know in advance if there are DevOps teams or individuals who can facilitate this way of managing code.

3. Monorepos can make security difficult, because, unlike other types of repositories, here you are granting a person who may only work on part of the project complete access to a codebase. Ideally, there should be independence between mono-repo projects; the versioning of each one should be established from the beginning to make it easier to deal with issues such as integrations and team coordination in relation to the maintenance of different code bases.

4. It’s important to evaluate the scalability of a monorepo; doing so allows us to establish early strategies to mitigate potential challenges as we scale. A pattern that can be valuable in this context is hexagonal architecture.

5. If an organization decides it wants to move from a monorepo to a multi-repo, it’s important it’s aware that this could lead to significant costs in terms of both time and effort.

What is a multi-repo?

A multi-repo is a software development approach where different projects or components of a larger application are stored and managed as separate repositories. Each project or component has its own version control repository, allowing teams to work on them independently. This approach contrasts with a monorepo, where all code is stored in a single repository. Multi-repo setups are often used to maintain clear boundaries between projects, enabling teams to work autonomously on different parts of a system while also potentially reducing conflicts that might arise when making changes.

What are the benefits and challenges of using a multi-repo?

We’ve already explored some of the benefits and challenges of monorepos. But to properly evaluate them it’s necessary to also recognize the pros and cons of their alternative.

Benefits

1. Security is one of the main benefits of using a multi-repo. This is because, unlike mono-repos, in this strategy it’s possible to grant specific and necessary permissions according to the specific scope of a project.

2. With a multi-repo, scalability should be much more feasible and manageable from the beginning. This is because projects are abstracted earlier.

3. Versioning is also almost instantaneous when you use a multi-repo — when you have separate environments in multiple different repositories, little coordination is required.

4. With a multi-repo it is much easier to assign ownership since, for example, each repository can satisfy a specific business domain.

5. The independence and performance provided by multi-repos makes it much easier for organizations to distribute their resources and evaluate results.

6. Migrating multi-repos to alternative ways of managing a codebase is much easier to do, compared to mono-repos

7. It’s much easier to do CI/CD with a multi-repo. This is because there is a basic separation, which makes it easier to facilitate resources between teams.

Challenges

1. Applying clean code and refactors can be difficult when you use a multi-repo. Although there are early workarounds to mitigate the way things are done between each team, code duplication is highly likely.

2. Running unit and integration tests are generally straightforward when using a multi-repo, but running end-to-end tests can be a challenge. This is because when you separate your codebase, you will inevitably require output from different repositories. Fortunately, this can be mitigated by having Quality Assurance (QA) people on the team who are dedicated to testing the full flow of an application.

3. Managing dependencies can cause friction between teams if a periodic management strategy that allows teams to obtain and implement the latest versions is not established.

4. Although having separate teams has advantages — as we saw above — there are also some disadvantages. These include:

   1. Isolation between equipment can undermine effective engineering practices and communication between people.

   2. If you lack a robust onboarding culture, it can be very difficult to incorporate new members into the team in a successful and healthy way.

   3. Prioritization is inevitable and will inevitably be present in each team, but it can be somewhat complex to manage when teams are separate. This is because  each team will want to achieve its own objectives, but as is often the case in the software industry, problems are presented as bugs or differences of opinion. If priorities are managed effectively, it can be the difference between an environment of chaos and rivalry and co-creation and empathy.

Symbology

✅ (Benefit) = Represents something obtainable without much effort.

⚠️ (Attention) = Represents something not easily obtainable.

❌ (Challenge) = Represents something difficult to obtain.  

Recommendations

I have shown you the challenges and benefits of both monorepos and multi-repos. To conclude, I would like to share with you some recommendations for both scenarios, based on my experience.

Mono-Repo

1. Today, tools like Nx and Lerna can help us manage generic web applications, or even micro front-end and mobile applications from a monorepo in a much easier manner than we were able to previously. I recommend exploring them..

2. Establishing a culture of good documentation from the start will go a long way towards successful onboarding.

3. In the same way, it’s important to consider that the pull request process, dependency management and quality may be affected, when this type of repository contains — or could contain in the future — a large number of projects. We have to consider and reflect on this when considering a monorepo as an option.

Multi-Repo

1. I recommend generating standards and establishing good practice from the beginning. Doing so will reduce inconsistencies in how code is written and implemented. This can be done through a wiki (using a tool like confluence), to document and articulate team consensus.

2. I also suggest implementing a consistent and dynamic design system early on if you decide to use a multi-repo. It can be very helpful when managed well.