Monorepo vs. Polyrepo: One Repository or Many?

WHY IT EXISTS: As software systems grow, managing code across multiple projects and teams becomes a major challenge. The core question is how to structure your codebase: do you optimize for cross-team collaboration and consistency, or for team autonomy and decoupling? This choice leads to two main strategies: monorepo or polyrepo.

THE MENTAL MODEL: Think of it as a city versus a collection of towns. A monorepo is a single large city. All projects live within its boundaries. It has shared infrastructure (build systems, CI/CD pipelines) and shared laws (linting, code style). Making a change that affects the whole city, like updating a bridge, is one coordinated effort. A polyrepo is a collection of independent towns, each with its own infrastructure and laws. To share anything, one town must build a road and the other must agree to connect to it, often with formal contracts like API versions.

HOW IT WORKS: In a monorepo, all projects—frontend, backend, mobile apps—are directories inside a single version control repository. A single commit can modify code across multiple projects, enabling atomic refactors. This requires specialized, smart build systems that can identify and build only the affected parts of the codebase. In a polyrepo, each project has its own repository. To share code, one project publishes a versioned artifact (like a library or package), and other projects consume it as a dependency, managing versions individually.

WHEN TO USE IT: A monorepo strategy is powerful when you have many tightly coupled projects, require large-scale atomic refactors, and have the engineering resources to invest in the necessary tooling. It simplifies dependency management by ensuring everyone uses the same version of internal libraries. This is why large companies like Google and Meta use them.

WHEN NOT TO USE IT: A polyrepo is the simpler, often better default. Avoid a monorepo if your projects are largely unrelated, if teams require high autonomy in their tooling and release schedules, or if you cannot afford to maintain the complex build infrastructure. Git itself can also become slow with the massive history and file count of a large monorepo.

ONE CANONICAL EXAMPLE: Google maintains one of the world's largest monorepos, containing the source code for almost all of its software. This allows an engineer to change a core library and, in the same commit, update every single application that depends on it. This process is managed by their sophisticated, open-source build tool, Bazel, which ensures only the truly affected code is re-tested and re-built.