What is a monorepo?
A monorepo is a single version-control repository that holds the code for many projects, libraries, and services at once. Instead of giving every app and shared package its own repo, you put them all in one place and version them together.
The opposite approach is a polyrepo (sometimes called multi-repo): each project, library, or service lives in its own repository with its own history, pull requests, and release cycle. Both are valid. The choice is about how you want code, dependencies, and teams to fit together, not about which one is "modern".
In plain words
Think of a monorepo as one big filing cabinet for the whole company, with a labelled drawer for each project. Everything shares the same cabinet, the same key, and the same filing rules. A polyrepo is the opposite: every project gets its own separate cabinet in its own room. The filing cabinet does not write your documents for you, it just decides whether they all live together or apart.
Big engineering organisations made the term famous. Google, Meta, and Microsoft run enormous monorepos. But you do not need their scale to benefit, and you do not automatically need a monorepo just because they use one.
Benefits and trade-offs
A monorepo shines when projects depend on each other and change together.
- One change, one pull request. When you update a shared library, you can fix every project that uses it in the same commit. No waiting for three separate repos to release.
- Easy code sharing. Shared components, types, and utilities sit right next to the code that uses them. No publishing a package to use it internally.
- Consistent tooling. One set of lint rules, one formatter, one test setup, one CI pipeline for everyone.
- Visible dependencies. You can see what depends on what, because it is all in one graph.
The trade-offs are real, though.
- The repo gets big. Cloning, indexing, and searching slow down as the codebase grows. Large monorepos need tooling like Nx, Turborepo, or Bazel to stay fast.
- CI has to be smart. You do not want to rebuild and retest everything on every commit. You need build caching and "affected project" detection.
- Access control is coarser. Everyone with access to the repo can see everything in it, which is not always what you want.
The short version: a monorepo trades a heavier setup for tighter integration.
When it fits, and when it does not
A monorepo fits well when:
- Your projects share a lot of code or change together (a web app, its mobile client, and a shared design system).
- You have a small number of teams who coordinate closely.
- You want one consistent way to build, test, and ship everything.
Lean toward separate repos when:
- Projects are truly independent and rarely touch the same code.
- Teams release on very different schedules and own their own deploy pipeline.
- You need strict, fine-grained access control between projects.
- The project is small or short-lived and a single repo is plenty.
If you are unsure, start simple. A small project does not need a monorepo. Reach for one when sharing code across repos starts to hurt.
Common pitfalls
- Confusing a monorepo with a monolith. A monorepo is about where the code lives. A monolith is about how the app is built and deployed as one unit. You can have a monorepo full of small, independent services, and you can have a monolith split across several repos.
- Skipping the tooling. A monorepo without build caching and affected-project detection turns CI into a slow, expensive bottleneck. Pick a tool early.
- Treating it as a dumping ground. One repo does not mean no structure. Clear ownership, folder conventions, and boundaries between projects matter more, not less.
- Adopting it because Google does. Their problems are not your problems. Choose the layout that fits your team size and how your projects actually relate.
Related articles:
- Context engineering: a new developer skill - Giving AI tools the right context, which matters even more in a large shared codebase.
- What is Cursor and what can it do? - The AI code editor and how it reads your project.
- Claude Code vs Cursor vs Copilot: from practice - Comparing AI coding tools on real work.
Want to stay one step ahead?
Don't miss our best insights. No spam, just practical analyses, invitations to exclusive events, and podcast summaries delivered straight to your inbox.