The World City, The Builder's Choice

Monorepo vs polyrepo, the strategic decision

Monorepo vs Polyrepo

When a team or company manages multiple projects, two approaches stand opposed:

Polyrepo - one repository per project

This is the most common approach. Each project, service or library has its own Git repository.

# Polyrepo - each project is a separate repository
github.com/my-team/frontend       # React application
github.com/my-team/backend-api    # Node.js API
github.com/my-team/auth-service   # Authentication service
github.com/my-team/shared-utils   # Shared library
github.com/my-team/mobile-app     # Mobile application
github.com/my-team/infra          # Terraform configuration

Advantages:

• Each project is independent - its own history, its own branches, its own CI
• Fine-grained permissions: you can grant access to one repository without granting access to the others
• Fast clones: each repository is lightweight
• Simplicity: no special tooling needed
• Autonomous teams: each team manages its repository as it sees fit

Disadvantages:

• Code sharing is difficult: the shared library must be published as a package, with its own version
• Cross-cutting refactoring is painful: changing an API impacts multiple repos = multiple PRs, multiple reviews, multiple deployments
• Inconsistencies: each repository can use different versions of tools, linters, frameworks
• Dependency hell: managing versions between interdependent repositories

Monorepo - everything in a single repository

The monorepo approach puts all the code from the organization into a single giant Git repository.

# Monorepo - everything in a single repository
github.com/my-team/platform/
├── apps/
│   ├── frontend/        # React application
│   ├── backend-api/     # Node.js API
│   ├── mobile-app/      # Mobile application
│   └── auth-service/    # Authentication service
├── packages/
│   ├── shared-utils/    # Shared library
│   ├── ui-components/   # Shared UI components
│   └── config/          # Shared configuration (ESLint, TS, etc.)
├── infra/               # Terraform configuration
└── docs/                # Centralized documentation

Advantages:

• Trivial code sharing: importing a shared package = a simple import, no version publishing
• Atomic refactoring: change a shared API + all its consumers in a single commit
• Consistency: one version of tools, one configuration, one standard
• Visibility: everyone sees all the code (transparency)
• Simple integration tests: everything is there, no need to mock other services

Disadvantages:

• Size: the repository can become enormous (GB of history)
• Tooling required: Git alone isn't enough, you need specialized tools
• Complex CI/CD: building and testing everything on each commit would be too slow
• Permissions: everyone sees everything (can be a disadvantage in some contexts)
• Training: the team must learn new tools

Who uses what?

The cost of a monorepo

A monorepo isn't free. Before diving in, make sure you understand what it entails:

Tooling

You'll need to set up and maintain tools like Nx, Turborepo or Bazel. These tools have their own learning curves and their own bugs. Someone on the team will need to become the expert.

Training

All developers need to understand the new workflows. "Why doesn't my build run everything?" "How do I target a single project?" "Why is the cache giving me an old result?" Plan time for training.

More complex CI

CI needs to be smarter. Instead of a simple "npm test", you need to implement affected detection, distributed cache, and parallelization. CI pipelines are more complex to write and debug.

Git under pressure

Git wasn't designed for repositories of several GB. You'll need to use partial clone, sparse checkout, and potentially git maintenance to keep performance acceptable.

# Enable automatic Git maintenance
# (optimizes pack files, updates indexes, etc.)
git maintenance start

# This launches background tasks:
# - gc: orphaned object cleanup
# - commit-graph: speed up history traversal
# - prefetch: pre-fetch objects from the remote
# - loose-objects: consolidate loose objects
# - incremental-repack: incremental pack file repacking

When to choose a monorepo?

• Your projects share a lot of code between them
• You regularly do cross-cutting refactorings
• You want to enforce uniform standards (linter, formatter, conventions)
• You have the resources to invest in tooling
• Your team is ready to learn new tools

When to stay with polyrepo?

• Your projects are very independent from each other
• You have autonomous teams with different technologies
• Simplicity is your priority
• You don't have the resources to invest in monorepo tooling
• Access permissions to code must be strictly separated