Monorepo Explained - NFHN Reader

Understanding Monorepos

Monorepos are hot right now, especially among Web developers. We created this resource to help developers understand what monorepos are, what benefitsthey can bring, and the tools available to make monorepo development delightful.

There are many great monorepo tools, built by great teams, with different philosophies. We do our best to represent each tool objectively, and we welcome pull requests if we got something wrong!

The tools we'll focus on are: Bazel (by Google), Gradle Build Tool (by Gradle, Inc), Lage (by Microsoft), Lerna, moon (by moonrepo), Nx, Pants (by the Pants Build community), Rush (by Microsoft), and Turborepo (by Vercel). We chose these tools because of their usage or recognition in the Web development community.

What is a monorepo

Let's start with a common understanding of what a Monorepo is.

Why a monorepo

What are the situations solved by monorepos.

Features of a monorepo

What to expect from a monorepo tool

Let's go deeper into the rabbit hole.

A “Polyrepo”

For the sake of this discussion, let's say the opposite of monorepo is a "polyrepo". A polyrepo is the current standard way of developing applications: a repo for each team, application, or project. And it's common that each repo has a single build artifact, and simple build pipeline.

The industry has moved to the polyrepo way of doing things for one big reason: team autonomy. Teams want to make their own decisions about what libraries they'll use, when they'll deploy their apps or libraries, and who can contribute to or use their code.

Those are all good things, so why should teams do anything differently? Because this autonomy is provided by isolation, and isolation harms collaboration. More specifically, these are common drawbacks to a polyrepo environment:

Polyrepo

Cumbersome code sharing

To share code across repositories, you'd likely create a repository for the shared code. Now you have to set up the tooling and CI environment, add committers to the repo, and set up package publishing so other repos can depend on it. And let's not get started on reconciling incompatible versions of third party libraries across repositories...

Polyrepo

Significant code duplication

No one wants to go through the hassle of setting up a shared repo, so teams just write their own implementations of common services and components in each repo. This wastes up-front time, but also increases the burden of maintenance, security, and quality control as the components and services change.

Polyrepo

Costly cross-repo changes to shared libraries and consumers

Consider a critical bug or breaking change in a shared library: the developer needs to set up their environment to apply the changes across multiple repositories with disconnected revision histories. Not to speak about the coordination effort of versioning and releasing the packages.

Polyrepo

Inconsistent tooling

Each project uses its own set of commands for running tests, building, serving, linting, deploying, and so forth. Inconsistency creates mental overhead of remembering which commands to use from project to project.

We can end up in pretty tricky situations when working in a polyrepo. But how can a monorepo help solve all of them?

Monorepo

No overhead to create new projects

Use the existing CI setup, and no need to publish versioned packages if all consumers are in the same repo.

Monorepo

Atomic commits across projects

Everything works together at every commit. There's no such thing as a breaking change when you fix everything in the same commit.

Monorepo

One version of everything

No need to worry about incompatibilities because of projects depending on conflicting versions of third party libraries.

Monorepo

Developer mobility

Get a consistent way of building and testing applications written using different tools and technologies. Developers can confidently contribute to other teams’ applications and verify that their changes are safe.

It's complex, we know. But you're not alone in this journey.

A monorepo changes your organization

It is more than code & tools. A monorepo changes your organization & the way you think about code. By adding consistency, lowering the friction in creating new projects and performing large scale refactorings, by facilitating code sharing and cross-team collaboration, it'll allow your organization to work more efficiently.

Here is a curated list of useful videos and podcasts to go deeper or just see the information in another way.

Monorepo books

Here is a curated list of books about monorepos that we think are worth a read.

Contributors

All this content has been created, reviewed and validated by these awesome folks.