Monorepo Architecture

Monorepos—multiple projects in a single repository—have gone from niche to mainstream. Tools like Nx and Turborepo have made them practical. But monorepos are not always the right choice. This guide covers when they make sense, how to structure and tool them, and the scaling challenges you'll face.

Monorepo vs Polyrepo: Honest Trade-offs

Monorepo: Single Repo, Multiple Packages

All code lives in one repository. Shared packages are referenced via workspace protocol ("@acme/ui": "workspace:*"). One CI pipeline, one place for issues and PRs, atomic cross-package changes.

Polyrepo: One Repo per Package/App

Each package or app has its own repo. Dependencies are published to a registry (npm) and versioned. Independent release cycles, clearer ownership, but cross-repo changes require multiple PRs and coordinated releases.

The Real Trade-offs

Monorepo advantages: Atomic refactors across packages, shared tooling and config, simpler dependency management for internal packages, easier to discover and reuse code.

Monorepo disadvantages: Larger repo (slower clones, git operations), higher risk of accidental coupling, need for discipline and tooling to scale, CI can become complex.

Polyrepo advantages: Clear boundaries, independent versioning and deploys, smaller repos, teams can own repos fully.

Polyrepo disadvantages: Cross-repo changes are painful, version skew between packages, duplicate config and tooling.

Choose based on team structure, release coupling, and how much you share. If you ship one product with many packages that change together, monorepo often wins. If you have independent products or teams that rarely coordinate, polyrepo may be simpler.

When a Monorepo Makes Sense

Shared Component Libraries

When multiple apps consume the same UI components, a monorepo lets you develop and version them together. Change a button in @acme/ui, run affected app tests, merge. No publish step for local development.

Multiple Apps with Coordinated Releases