Monorepo vs Polyrepo: How to Structure Your Backend Projects

#backend #architecture #devops #webdev

Monorepo vs Polyrepo: How to Structure Your Backend Projects

One giant repo or many small ones? Both have trade-offs. Here is how to decide.

Monorepo

All services, libraries, and tools in a single repository.

my-company/
  packages/
    shared-types/     # Shared TypeScript types
    logger/           # Common logging library
    db-client/        # Database client wrapper
  services/
    api-gateway/      # Express API gateway
    user-service/     # User management
    billing-service/  # Stripe integration
  tools/
    cli/              # Internal CLI tools
  package.json        # Workspace root
  turbo.json          # Turborepo config

Pros: Atomic cross-service changes, shared code without publishing packages, single CI/CD pipeline, easy refactoring.

Cons: Slow CI without caching, complex permissions, intimidating for new developers.

Polyrepo

Each service gets its own repository.

Pros: Clear ownership, independent deploys, simpler CI per repo, smaller clone sizes.

Cons: Shared code requires published packages, cross-service changes need multiple PRs, version drift.

When to Use What

Small team (1-5 devs): Monorepo. The overhead is minimal and sharing code is easy.
Medium team (5-20): Monorepo with Turborepo/Nx. Caching makes CI fast enough.
Large org (20+): Consider polyrepo with shared packages, or invest in monorepo tooling (Bazel).