“Just put it in the monorepo” is not a strategy.

Monorepos help when teams share libraries and can enforce tooling. Multi-repos help when blast radius and access control matter more than atomic cross-package PRs. The wrong choice is the one that mismatches who deploys what.

Nested boxes with indigo ribbon

Containment or coupling — choose on purpose.

Choose monorepo when

  • Shared design system with frequent coordinated changes
  • One platform team owns CI standards
  • Atomic refactors across packages are common
  • You can invest in remote caching and ownership CODEOWNERS

Choose multi-repo when

  • Different security boundaries or vendors
  • Release cadences wildly differ (brochure daily, app weekly)
  • Access must stay least-privilege per surface
  • Separate agencies or teams should not see each other’s code

Repo topology diagram

Hybrid that often works

Publish the design system as a versioned package. Apps consume versions. That requires versioning discipline — which is healthier than invisible breakage inside one giant main.

Failure modes

  • Monorepo where any PR can break production homepage without review
  • Multi-repo with five copies of the button and no release train for the system
  • “We’ll extract later” without a boundary

Closing

Draw team boundaries first. Repo topology should follow. Fashionable tooling on the wrong topology still hurts.

Need a repo topology decision for web surfaces? Start a project inquiry.

CI cost

Monorepos need path filters so a docs typo does not rebuild all apps. Without that, developers bypass CI.

Ownership files

CODEOWNERS (or equivalent) for packages that can break production. Homepage package should not be mergeable by every contractor.

Package publishing

If hybrid: changelog discipline, canary versions, and a consumer upgrade schedule. Abandoned major versions of the design system recreate multi-repo sprawl inside the monorepo.

Decision worksheet

Score 1–5:

  • Shared UI change frequency
  • Need for separate access control
  • Difference in release cadence
  • CI expertise available
  • Blast radius sensitivity of homepage

High shared UI + high CI skill → monorepo lean. High blast radius + multi-vendor → multi-repo lean.

Case sketches

Studio with one web team and a design system: monorepo often wins. Shared lint, shared tokens, atomic updates.

Enterprise with agency on marketing and internal team on app: multi-repo or hybrid. Agencies should not need production app secrets to change a homepage hero.

Multiple brands with shared platform: monorepo packages per brand surface, or multi-repo with a platform package registry — decide based on release independence.

Migration costs

Moving to a monorepo is not free: CI rewrite, permission model, developer education. Do not migrate for aesthetics. Migrate when coordination pain exceeds migration pain.