Monorepo: Managing Multiple Projects in One Repository

WHY IT EXISTS Managing dependencies and ensuring consistency across many separate repositories is complex. A change in a shared library requires updating and deploying every project that uses it, leading to versioning conflicts. Monorepos were created to solve this by centralizing code and simplifying cross-project changes.

THE MENTAL MODEL Think of a monorepo not as one giant project, but as a city containing many distinct buildings (projects) that all share the same infrastructure (build tools, dependencies). A change to the city's power grid (a shared library) can be instantly verified against every building it affects, all within a single commit.

HOW IT WORKS All code for multiple distinct projects (e.g., a web frontend, a backend API, a design system library) lives in a single Git repository. Specialized tooling is crucial to manage this. These tools understand the dependency graph between projects, so when a file is changed, they can run tests and builds for only the affected projects, avoiding a full rebuild of the entire repository. This allows for atomic commits that span multiple projects.

WHEN TO USE IT Use a monorepo when you have multiple projects that are tightly coupled or share significant code, like a component library used by several frontends. It simplifies dependency management (no need to publish and consume internal packages) and enables large-scale atomic refactors. Companies like Google, Meta, and Microsoft use them to manage massive, interconnected codebases.

WHEN NOT TO USE IT Avoid a monorepo if your projects are completely unrelated and developed by siloed teams with no shared dependencies. The overhead of specialized tooling and the potential for a slower version control experience (e.g., large checkouts) can outweigh the benefits. If teams need full autonomy over their toolchains and release cycles, multiple repositories are a better fit.

ONE CANONICAL EXAMPLE A design system team manages a shared component library in a monorepo alongside three web applications that use it. When they update a Button component, a single pull request can contain the change to the library AND the necessary adjustments in all three applications. The CI pipeline automatically tests the component and all three apps, ensuring no breaking changes are introduced. This single, atomic commit guarantees consistency across the entire product suite.