Monorepo vs Multirepo: Choosing a Repository Layout
One repository or many? Learn the trade-offs, the tooling each layout needs, and the signals that point to the right choice.
By Velloreth
The two layouts
Monorepo — one repository, many projects.
repo/
├── apps/
│ ├── web/
│ └── api/
├── packages/
│ ├── ui/
│ └── shared/
└── package.json
Multirepo — one repository per project.
web/ (repo)
api/ (repo)
ui/ (repo)
shared/ (repo)
The case for a monorepo
Atomic cross-project changes. A change to a shared library and its consumers is one commit, so the repository is never in a broken intermediate state.
In a multirepo, the same change is a pull request in the library, a version bump, and a pull request in each consumer. Between them, the consumers are on the old version, and the change is not atomic.
One toolchain. Linting, formatting, testing, and CI configuration are shared. A new project inherits them.
Easier refactoring. A rename across projects is a single search and replace, verified by one build.
Consistent dependencies. One lockfile means one version of a shared dependency, which avoids the “three versions of React” problem.
Discoverability. The code is in one place, so finding an implementation is a search rather than a guess about which repository.
The case for a multirepo
Clear ownership. Each repository has an owner, and access control is per repository.
Independent versioning. A library can release 1.2.3 without touching the applications.
Independent CI. A change to one project runs only that project’s pipeline, with no affected-project detection needed.
Smaller clones. A developer working on one service clones only that service.
Technology freedom. Each repository can use its own toolchain without coordinating with the others.
Blast radius. A broken build in one repository does not block everyone.
The real trade-offs
| Monorepo | Multirepo | |
|---|---|---|
| Cross-project change | One commit | Several PRs |
| CI complexity | High (needs scoping) | Low |
| Access control | Coarse | Per repo |
| Versioning | Unified or coordinated | Independent |
| Refactoring | Easy | Hard |
| Clone size | Large | Small |
| Tooling investment | High | Low |
| Ownership clarity | Weaker | Stronger |
The monorepo tooling problem
The main cost of a monorepo is CI. Without scoping, every change runs every test.
Affected-project detection is the solution: determine which projects a change touches, and run only their tasks.
# Turborepo
turbo run test --filter='...[origin/main]'
# Nx
nx affected --target=test --base=origin/main
The --filter and --affected flags compute the set of projects affected by the change, including dependents.
Remote caching stores task results, so a task that has already run on the same inputs is not re-run.
turbo run build --remote-cache
This is what makes a large monorepo practical: a developer’s build reuses results from CI and from other developers.
Workspace linking makes a local package resolvable by name.
{
"workspaces": ["apps/*", "packages/*"]
}
# pnpm-workspace.yaml
packages:
- "apps/*"
- "packages/*"
The multirepo coordination problem
The main cost of a multirepo is a cross-project change.
The version bump dance. Change the library, release a version, bump the version in each consumer, and open a pull request in each. The consumers are on the old version until each is merged.
The diamond dependency. Two libraries depend on a third, and they need different versions. The package manager resolves it, but the application may end up with two copies.
The discovery problem. Finding which repositories use a library requires a search across repositories, which is harder than a search in one.
The drift problem. Shared configuration is copied, and the copies diverge.
Choosing
A monorepo fits when:
- Projects are tightly coupled and change together.
- You want atomic cross-project changes.
- One team owns most of the code.
- You are willing to invest in tooling.
A multirepo fits when:
- Projects have genuinely independent lifecycles.
- Different teams own different projects with different access needs.
- The projects use different stacks.
- You want simple CI without a task runner.
The signal that matters most is coupling. If a change to one project usually requires a change to another, a monorepo removes friction. If the projects rarely change together, a multirepo keeps things simple.
A middle path
A monorepo for the tightly coupled core, and separate repositories for the rest. The shared libraries and the applications that use them live together, and an independent tool lives on its own.
A meta-repository that pins versions of several repositories, used for integration testing. Each project keeps its own repository, and the meta-repository records a consistent set.
Practical guidance
- Choose based on coupling, not on repository size.
- Invest in affected-project detection for a monorepo.
- Use remote caching to make a monorepo practical.
- Use a workspace manager to link local packages.
- Keep CI fast in either layout.
- Do not split a monorepo without a concrete reason.
- Do not merge repositories just to reduce the count.
- Revisit the decision as the team and the code change.
For the related guides, see git-submodules-vs-subtrees and ci-cd-pipeline-basics. For the broader context, twelve-factor-app-explained and git-branching-strategies.
Quotable summary
A monorepo puts many projects in one repository, which makes cross-project changes atomic, while a multirepo gives each project its own repository, which gives clear ownership and independent versioning. The main cost of a monorepo is tooling, because builds and tests must be scoped to what changed, and the main cost of a multirepo is coordination, because a cross-project change becomes several pull requests. The choice is about team structure and coupling rather than repository size: if a change to one project usually requires a change to another, a monorepo removes friction. A monorepo is not a monolith — a monolith is a single deployable application, while a monorepo is a layout that can hold many independent deployables.