Monorepo vs Polyrepo: When to Split and When to Keep Together

This debate comes up at every growing engineering team. Here's a framework for deciding.

What You're Actually Choosing

Monorepo: One repo, all packages. Single PR can touch frontend, backend, and shared libs.
Polyrepo: Separate repos per service. Independent deploys, independent release cycles.

The Monorepo Case

my-company/
  apps/
    web/        # Next.js
    mobile/     # React Native
    api/        # Express
  packages/
    ui/         # shared components
    types/      # shared TypeScript types
    utils/      # shared utilities
    config/     # shared ESLint, TS configs

When to use it:

• Apps share significant code (types, components, utils)
• Small to medium team (1-50 engineers)
• You want atomic cross-package changes
• You don't need independent release cycles per service

Real benefits:

• One PR to update a shared type across all consumers
• Dependency updates in one place
• Easier refactoring across package boundaries
• Single CI pipeline to understand

The Polyrepo Case

my-company/web-app
my-company/mobile-app
my-company/payments-service
my-company/notifications-service
my-company/shared-types  # published npm package

When to use it:

• Services need truly independent deploy cadences
• Different teams own different services with no shared code
• Services use different languages (Node + Go + Python)
• Security/compliance requires code isolation

Real benefits:

• Smaller git history per repo (faster clones)
• Independent CI — a test failure in service A doesn't block service B
• Teams can move at their own pace

The Hybrid: Micro-Monorepo

Most companies land here:

product-monorepo/     # frontend + BFF + shared
  apps/web
  apps/api
  packages/ui
  packages/types

payments-service/     # separate — different team, different deploy
notifications-service/  # separate — different cadence

Keep tightly coupled code together. Separate genuinely independent services.

Tooling for Monorepos

# Turborepo (recommended for JS/TS)
npx create-turbo@latest
turbo build        # builds all packages in dependency order
turbo build --filter=web  # build only web + its deps

# Nx (more opinionated)
npx create-nx-workspace@latest

# pnpm workspaces (foundation for both)
pnpm install  # installs all workspace packages
pnpm --filter web dev  # run dev in web only

Decision Heuristic

Do you share code between apps?
  Yes → monorepo (or stay there)
  No  → polyrepo

Do you need independent deploys?
  Yes, always → polyrepo
  Only sometimes → monorepo with separate CI jobs per app

Team size?
  <50 engineers → monorepo works fine
  >200 engineers → polyrepo for org boundaries
  50-200 → depends on structure

---

The Ship Fast Skill Pack includes a /deploy skill that generates Turborepo monorepo configs and CI pipelines. $49 one-time.