Understanding Monorepo
A monorepo stores the code for many projects, services, libraries, and sometimes infrastructure definitions, inside one version-control repository, rather than spreading them across separate repositories with independent histories. Large organizations including Google and Meta run famously enormous monorepos, and open-source projects such as Babel and React use the pattern at a smaller scale to keep related packages tightly coordinated.
How It Works
Once a repository grows beyond a handful of small projects, naive tooling breaks down: a plain git clone becomes slow, and running the full test suite on every change becomes impractical. Purpose-built monorepo tooling solves this. Tools such as Bazel, Nx, Turborepo, and Lerna build a dependency graph of the packages in the repository and support “affected” builds, meaning a change to one package only triggers builds and tests for that package and whatever depends on it, not the entire repository. Many of these tools also support remote build caching, so a build already performed by one developer or CI run does not have to be repeated by another.
Example
A company keeps its frontend application, backend API, a shared UI component library, and its Terraform infrastructure modules all in one repository. A CI pipeline runs nx affected –target=test on every pull request, which inspects the diff, determines that only the UI library and the frontend that depends on it were touched, and skips running tests for the backend and infrastructure code entirely, keeping CI fast even as the repository grows.
Monorepo vs. Polyrepo
A polyrepo approach gives each service or team its own repository, with independent versioning, release cadence, and access control, and clearer ownership boundaries. The trade-off is that cross-cutting changes, updating a shared library and every consumer of it in one atomic commit, become much harder, often requiring coordinated releases across several repositories. A monorepo makes that kind of atomic, cross-project change trivial, since everything lives in one commit history, at the cost of needing more sophisticated build tooling to keep things fast at scale.
Why Teams Use Monorepos
- Cross-project refactors, such as changing an API and updating every consumer, happen in a single pull request instead of a coordinated multi-repo release.
- Shared libraries stay on a single version across the codebase, avoiding the “dependency hell” of multiple teams pinned to different versions of the same internal package.
- Code sharing and discovery are easier since everything is visible in one place rather than scattered across dozens of repositories.
- CI/CD tooling and conventions can be unified rather than duplicated per repository.
Trade-offs and Limitations
A monorepo can grow to many gigabytes, and naive git operations, clone, checkout, blame, slow down without additional tooling such as shallow clones or sparse checkout. CI must be built around affected-based testing or build times balloon as the repository grows. Because everyone can see and, without safeguards, modify any part of the codebase, strong ownership conventions such as CODEOWNERS files become important to route reviews to the right team.
Best Practices
- Adopt an incremental build system, such as Bazel, Nx, or Turborepo, before the repository grows large enough for naive full-repo builds to become painful.
- Use CODEOWNERS or equivalent to route pull request reviews automatically to the right team for each part of the repository.
- Build CI around affected-package detection rather than testing the entire repository on every change.
- Define clear package boundaries and versioning conventions even though everything shares one repository.
Frequently Asked Questions
What is Monorepo?
A monorepo is a single version-control repository that holds the source code for multiple projects, services, or applications, in contrast to a polyrepo approach where each project lives in its own separate repository.
How does Monorepo work?
Monorepo works by combining the components described in the sections above. The main page walks through the architecture, the typical use cases, and the trade-offs to weigh before adopting it.
Why does Monorepo matter?
Teams adopt Monorepo to ship faster, run more reliably, and reduce the cognitive load on engineers. The benefits, limits, and adjacent tools are covered in the body above.
When should you use Monorepo?
Use Monorepo when the problems it solves match what your team is hitting today. The page above outlines the signals that mean you should adopt it now, and the cases where a simpler approach is fine.
