Monorepo

lastmod 2025-06-09created 2020-07-1011 edits

In version control systems, a monorepo is a software development strategy where code for many projects is stored in the same repository. As of 2017, this software engineering practice is over two decades old and is also called a 'shared codebase'.

Monorepo Projects

There are many solutions, but each has different goals.

• Monorepo
• Bazel (by Google) - A fast, scalable, multi-language and extensible build system.
• Gradle (by Gradle, Inc) - A fast, flexible polyglot build system designed for multi-project builds.
• Lage (by Microsoft) - Task runner in JS monorepos
• Lerna - A tool for managing JavaScript projects with multiple packages.
• Nx (by Nrwl) - Next generation build system with first class monorepo support and powerful integrations.
• Rush (by microsoft) - Geared for large monorepos with lots of teams and projects. Part of the Rush Stack family of projects.
• Turborepo (by Vercel) - The high-performance build system for JavaScript & TypeScript codebases.
• Pants
• Earthly

Choosing a Monorepo build tool

• Comparing Monorepo build tools - Bazel, Pants, NX, Earthly
  • [Original] Monorepo Build Tools - Earthly Blog
• Everything about Monorepo | GeekNews
  • [Original] Monorepo Explained
• Monorepo adoption is gradually increasing, but because of the problems tied to changes/caching/rebuilds, which tool you choose matters
• Key features to consider: language support, learning curve, caching, build checks, Versatility
• If your organization's development languages, workflow, and codebase size are similar to Google's, Bazel
• If you are unhappy with the cost of migrating to Bazel, its Python support, or writing BUILD files, Pants
• If it's mainly JavaScript / TypeScript, NX is also a great choice
• If you have containerized microservices, system-level dependencies, or somewhat non-standard tasks, Earthly

What is a Monorepo

• Monorepo Explained

Multiple separate projects held in a single Repo with well-defined relationships

Monorepo != Monolith

Why do it?

The reason people chose Polyrepo (the approach of using multiple Repos) was "team autonomy"

Teams can each choose the libraries they want and decide who contributes to and uses the code

• With PolyRepo
  • Sharing code is cumbersome
  • Lots of code duplication
  • Critical bugs and big changes in shared libraries are costly
  • Inconsistent development tools across projects
• With Monorepo
  • No overhead for creating new projects
  • Atomic commits across all projects
  • Everything managed with a single version number
  • Developer mobility (moving between projects)

Features provided by Monorepo tools and a comparison between tools

Bazel, Gradle, Lage, Lerna, Nx, Rush, Turborepo

• Local caching
• Local task orchestration
• Distributed caching
• Distributed task execution
• Transparent remote execution
• Detecting affected projects/packages
• Workspace analysis
• Dependency graph visualization
• Code sharing
• Consistent tooling
• Code generation
• Project constraints and visibility

A shift in mindset

A monorepo changes "the way you think about your organization and code"

• By adding consistency,
• reducing friction when creating new projects or performing large-scale refactoring,
• and promoting code sharing and cross-team collaboration,
• organizations can work more efficiently

See also

• Design pattern

Favorite site

• Wikipedia (en) Monorepo
• Monorepo? Yarn Workspace!. 🌸 Monorepo. Lerna? Yarn Worksapce! | by Ibong | Medium
• (Design Patterns) 👆 What is a Monorepo?
• Essential ingredients for building a productive monorepo | GeekNews
  • [Original] The Ingredients of a Productive Monorepo
  • Adopting a monorepo brings benefits such as organizational consistency, code sharing, and a stronger shared tooling environment, but simply following big tech's examples leads to new problems and challenges
  • A successful monorepo requires sticking to the principle of making every major operation O(change) rather than O(repo), and needs matching tools and strategies at each stage of build, test, and CI/CD
  • For source control, start with git and, as scale grows, consider gradual scaling such as sparse checkout and virtual file systems
  • For the build system, keep to a single language where possible, hold out as long as you can with each language's native build tools, and gradually move to Bazel/Buck2 etc. only when truly necessary
  • Testing and CI/CD should quickly detect only the scope affected by a change and build, test, and deploy just that; in a large monorepo, reliability strategies such as automatic test retries and isolating flaky tests are also essential