Monorepo vs. Polyrepo: The Trade-offs That Actually Matter

The monorepo-versus-polyrepo debate gets argued as if one is objectively correct, usually by citing a specific painful multi-repo migration or a well-known single-repo giant. Both structures work at scale — some of the largest engineering organizations run one enormous monorepo, and plenty of others run thousands of independent repos — which is a strong signal the choice is about what trade-offs your organization is better equipped to absorb, not which one is right.

What a Monorepo Actually Buys You

Atomic cross-project changes are the headline benefit: a shared library's API changes, and the same commit updates every caller, verified by one CI run, with no window where callers are on an incompatible version of a dependency they haven't updated yet.

One commit:
  libs/auth/token.ts          (breaking change)
  services/api/handler.ts     (updated call site)
  services/worker/consume.ts  (updated call site)
  -> single CI run verifies all three together, or the commit doesn't merge

It also makes code genuinely discoverable — one clone, one search, no guessing which of forty repos has the utility function you need — and simplifies dependency management, since there's exactly one version of any shared library in use at any moment, not a matrix of versions across repos slowly drifting apart.

What It Costs

The atomic-change benefit is also where the pain concentrates: tooling has to scale to the whole repo's size, which means investing in incremental build systems (Bazel, Nx, Turborepo) essentially becomes mandatory once the repo passes a certain size — a plain full install-and-test run across a multi-million-line monorepo is not a viable CI pipeline. Access control gets harder too: a monorepo either grants broad read access to the whole codebase or needs a path-based permission system layered on top, neither of which is free.

What a Polyrepo Actually Buys You

Independent deploy cadence is the real advantage, not "organization" in the abstract — a team can version, release, and roll back its service without any coordination with other teams' release schedules, and CI for one repo doesn't slow down because an unrelated repo's test suite is broken. Ownership boundaries are also enforced structurally rather than by convention: repo-level access control is the default, not an add-on.

What It Costs

Cross-cutting changes become their own project. Updating a shared library used by twelve services means twelve separate PRs, twelve separate review cycles, and, critically, a real window where some services are on the old version and some are on the new — which is either fine for a backward-compatible change or a genuine multi-week coordination effort for a breaking one. Dependency drift is the standing tax: without deliberate process, services quietly diverge on library versions until an upgrade becomes its own multi-sprint project.

The Actual Decision

Neither choice is permanent or irreversible in principle, but migrating between them is expensive enough in practice that it's worth being honest about which trade-offs your org already struggles with — a monorepo doesn't fix a coordination problem, and a polyrepo doesn't fix a discoverability problem; each just relocates where the cost shows up.