Monorepo

A monorepo keeps many projects in one repository, sharing tooling and dependencies while enabling atomic cross-project changes and a single review workflow.

delivery

Definition

A monorepo is a version control strategy that stores multiple applications, libraries, and services in a single repository, usually with tooling that understands project boundaries, shared dependencies, and affected-only builds.

Context and scope

It is chosen by organizations whose projects change together frequently, who want one dependency graph and one CI configuration, and who can invest in build tooling.

Common misconceptions

A monorepo means one deployable — it is one repository containing many independently deployable artifacts.
Monorepos are only for giants — small teams benefit too, but the tooling cost must be justified.
A monorepo removes versioning problems — internal packages still need versions or workspace protocols and clear ownership.

Anti-patterns

One root package.json installing every dependency for every project
Running the full test suite on every change instead of only affected projects
No ownership rules, so any team can change any package without review

Related concepts

Authoritative source

https://monorepo.tools/

One repository, many projects

A monorepo holds applications and shared libraries side by side. The value is not co-location by itself but the workflows it enables: a change to a shared library and every consumer can land in one commit, reviewed together and tested against each other. Modern tooling builds a dependency graph, runs tasks only for affected projects, and shares a cache across machines and CI runs.

repo/
  apps/web/
  apps/api/
  packages/ui/
  packages/config/
pnpm -r --filter "...[origin/main]" test

When to use it

Choose a monorepo when projects share code and change together, when dependency versions should be aligned, or when you want one CI configuration and one review culture. Avoid it when teams are fully independent, when repository size would slow clones beyond tolerance, or when access control must be strict per project. Compared with polyrepos, a monorepo simplifies atomic changes but concentrates tooling complexity.

Trade-offs

Clones and CI runs grow unless affected-only execution and caching are in place. Ownership boundaries need explicit rules such as CODEOWNERS. Tooling lock-in is real: migrating away from a monorepo tool is expensive. Access control is coarser, since repository permissions apply to everything inside.

Example and misconceptions

A team changes a button component in packages/ui. The affected graph rebuilds the component, then apps/web, and skips the API and docs. One pull request ships the change with tests for every consumer. The myth that a monorepo is a single deployment confuses repository layout with release topology. Related concepts: build cache, dependency pinning, and CI/CD.