Tech & AI, Explained

monorepo-vs-polyrepo

5 min read

Monorepo vs polyrepo: when to use which

Status: 🟩 COMPLETE Last updated: 2026-06-21 Plain-English tagline: One repo with many projects, or many repos with one project each. For solo developers and small teams, the choice mostly doesn’t matter. At scale, it matters a lot.

What this decides

You have multiple “things” — a webapp, a mobile app, a shared design system, an admin tool, scripts, docs. They can live in:

  • A single repository (monorepo) — all the things in one Git repo with subfolders
  • Multiple repositories (polyrepo / multi-repo) — each project in its own Git repo

For background: Git basics 🟩, GitHub 🟩 🟦.

The short answer

For solo developers and small teams, it mostly doesn’t matter. Default to single repos per project. If projects share code, consider a monorepo with a tool like Turborepo or Nx.

Monorepo wins when:

  • Projects genuinely share code (a UI library used by web + mobile + admin)
  • You want atomic cross-project changes (a schema change updating frontend + backend in one PR)
  • You want shared tooling, build pipelines, lint rules

Polyrepo wins when:

  • Projects are independent (no shared code, different teams, different deploy cadences)
  • Repo size or complexity becomes a problem
  • You need different access controls per project

Bible Quest is a single project = single repo. No monorepo needed.

The factors that matter

  1. Do projects share code? Yes → monorepo gives you internal package sharing without npm publishing. No → polyrepo is simpler.
  2. Do projects deploy together? Yes → monorepo simplifies coordinated changes. No → polyrepo prevents cross-coupling.
  3. How big does the repo get? Monorepos can become enormous; tooling helps but isn’t free.
  4. What’s the team structure? One team across projects → monorepo aids coordination. Different teams per project → polyrepo respects boundaries.
  5. How comfortable are you with monorepo tooling? Turborepo / Nx / pnpm workspaces have learning curves.

When to pick MONOREPO

  • You have a shared design system used by multiple apps.
  • You have shared TypeScript types (database types, API contracts) consumed by both frontend and backend.
  • You want atomic cross-cutting changes — “add a field to the user schema AND update every consumer” in one PR.
  • You want consistent tooling — one ESLint config, one Prettier config, one tsconfig.json base.
  • You’re a small team that touches everything.

Modern monorepo tools (2026):

  • Turborepo — Vercel’s tool. Fast incremental builds, remote caching. Strong for JS/TS projects.
  • Nx — Nrwl’s tool. Feature-rich, more opinionated, popular for large enterprises.
  • pnpm workspaces — simpler, just package management. Pair with Turborepo for builds.
  • Lerna — older; mostly superseded by Turborepo/Nx.
  • Bazel — Google’s tool. Powerful but heavy. Overkill for most.

Typical monorepo structure:

my-monorepo/
├── apps/
│   ├── web/              ← Next.js webapp
│   ├── mobile/           ← React Native app
│   └── admin/            ← internal tool
├── packages/
│   ├── ui/               ← shared React components
│   ├── types/            ← shared TypeScript types
│   └── utils/            ← shared helpers
├── package.json          ← root, with workspaces config
└── turbo.json            ← Turborepo build config

When to pick POLYREPO

  • Projects are genuinely independent. No shared code, no coordinated deploys.
  • Different teams own different projects. Repo boundaries match team boundaries.
  • Different access controls — public open-source repo + private app code.
  • Different release cadences. The mobile app ships monthly; the web app ships hourly.
  • You don’t want monorepo tooling complexity. Simple npm install, simple deploys.
  • It’s just one project. The monorepo argument doesn’t apply.

Bible Quest example: it’s one Next.js app. No second project. No “shared” code to extract. Polyrepo (single repo) is correct.

The hybrid (rare but valid)

You can have a monorepo for the apps that share code + separate repos for truly independent things.

Example:

  • my-product-monorepo — web + mobile + shared UI + shared types
  • marketing-site — separate; doesn’t share anything; published differently
  • internal-docs — separate; just markdown

Don’t over-engineer. Most teams either use one monorepo or polyrepo throughout; few intentionally split.

Common mistakes

  • Setting up a monorepo “for the future” before you have any shared code. The complexity costs are real; defer until you genuinely need it.
  • Letting a monorepo become a mega-repo without tooling. A 50-package monorepo without Turborepo builds is painful.
  • Spreading what should be one app across multiple repos. “Frontend repo + backend repo + types repo” for a single tightly-coupled product is usually wrong. Either one repo, or actually decouple them.
  • Using a monorepo to enforce coupling. If two services are deployed independently and called via API, they shouldn’t share types via monorepo — they should publish versioned contracts.

What if I’ve already chosen?

“I have polyrepos and want to consolidate”: evaluate first. Only consolidate if you genuinely have shared code or cross-cutting changes. Use git subtree or git filter-repo to migrate history into a monorepo without losing it.

“I have a monorepo and want to split”: harder. Identify which packages are independent enough to extract. git filter-repo lets you keep history. Be prepared for CI / tooling re-setup.

“My monorepo build is slow”: the right move is usually Turborepo (or Nx). Caching + parallelism + incremental builds make even large monorepos fast.

“My polyrepo is creating coordination problems”: evaluate which problems specifically. Sometimes the fix is monorepo; sometimes it’s better contracts between independent repos.

Solo / small-team reality

For Bible Quest and projects like it: one repo, no monorepo tooling, no overthinking. The monorepo conversation is for teams with multiple products, multiple platforms, and >5 developers. Below that, the simplicity of a normal Git repo wins.

If your single-project repo grows to need shared code (you start a second app or a mobile companion), THAT’S when the monorepo conversation begins.

See also

Sources

Graph View

Backlinks