Monorepo vs Multi-Repo: Engineering Tradeoffs

Table of Contents:

• Repository Strategy Comparison
• Monorepo Architecture
• Multi-Repo (Polyrepo) Architecture
• Tooling Landscape
• CI/CD and Build Performance
• Code Sharing Patterns
• Dependency Management
• Team Organization
• Migration Strategies
• Scaling Patterns
• Decision Matrix
• Production Checklist
• Frequently Asked Questions

Repository Strategy Comparison

Short answer: Use monorepo for tightly coupled services needing atomic changes and shared code, multi-repo for independent teams with separate release cycles, and hybrid (monorepo per domain) for large organizations.

If you searched "monorepo vs multi-repo", you're scaling engineering teams and need to choose repository architecture. At HinterBuild, our backend API engineering team deploys both patterns — monorepo for startups building integrated platforms, multi-repo for enterprises with autonomous product teams.

Key Takeaways:

• Monorepo enables atomic cross-service changes but requires sophisticated build caching
• Multi-repo provides team autonomy but complicates shared library versioning
• Google, Meta, Microsoft use monorepo for 100K+ engineers — not just for small teams
• Turborepo, Nx, Bazel make monorepo CI/CD fast with incremental builds
• Hybrid patterns (monorepo per product line) balance benefits

This guide covers monorepo vs multi-repo decision criteria, tooling trade-offs, and production patterns from real codebases at scale.

Quick Decision Matrix

Monorepo Architecture

Single repository containing multiple projects with shared tooling and dependencies.

Monorepo Structure

my-company/
├── apps/
│   ├── api/                  # FastAPI backend
│   │   ├── src/
│   │   ├── tests/
│   │   └── pyproject.toml
│   ├── web/                  # Next.js frontend
│   │   ├── src/
│   │   └── package.json
│   ├── mobile/               # React Native
│   └── admin/                # Internal dashboard
├── packages/
│   ├── shared-types/         # TypeScript types
│   ├── ui-components/        # React components
│   ├── api-client/           # Generated API client
│   └── auth/                 # Auth utilities
├── services/
│   ├── user-service/         # Go microservice
│   ├── payment-service/      # Go microservice
│   └── notification-service/
├── tools/
│   ├── scripts/              # Shared build scripts
│   └── configs/              # Linting, formatting
├── .github/
│   └── workflows/            # CI/CD pipelines
├── turbo.json                # Turborepo config
└── pnpm-workspace.yaml

Monorepo Tools Comparison

Turborepo Example

// turbo.json
{
  "$schema": "https://turbo.build/schema.json",
  "pipeline": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**", ".next/**"]
    },
    "test": {
      "dependsOn": ["build"],
      "outputs": []
    },
    "lint": {
      "outputs": []
    },
    "dev": {
      "cache": false,
      "persistent": true
    }
  }
}

turbo run build --filter=...@origin/main

# Run tests in parallel with caching
turbo run test --concurrency=8

# Dev mode with automatic rebuilds
turbo run dev --filter=web --filter=api

Python Monorepo with Poetry

# pyproject.toml (root)
[tool.poetry]
name = "my-company"
version = "1.0.0"

[tool.poetry.dependencies]
python = "^3.11"

[tool.poetry.group.dev.dependencies]
pytest = "^7.4"
ruff = "^0.1"

# Workspace packages
[tool.poetry.source]
name = "internal"
url = "packages/*"

# apps/api/pyproject.toml
[tool.poetry]
name = "api"
version = "1.0.0"

[tool.poetry.dependencies]
python = "^3.11"
fastapi = "^0.110"
shared-types = { path = "../../packages/shared-types", develop = true }
auth = { path = "../../packages/auth", develop = true }

Advantages

✅ Pros:

• Atomic changes: Refactor API + frontend in single commit
• Code reuse: Shared libraries without npm publish
• Consistent tooling: Single ESLint/Prettier config
• Easier refactoring: Find all usages across projects
• Single CI pipeline: Test everything together
• No version hell: Always use latest shared code

❌ Cons:

• Build complexity: Requires incremental build tools
• Large clone size: Git repo grows with all projects
• Slower git operations: Git log/blame on large histories
• Access control: All-or-nothing repo access
• CI bottleneck: Full build can take hours without caching

Pair with CI/CD best practices for monorepo deployment pipelines.

Multi-Repo (Polyrepo) Architecture

Separate repository per project with independent versioning and releases.

Multi-Repo Structure

Company Repos:
├── api (github.com/company/api)
│   └── FastAPI backend
├── web (github.com/company/web)
│   └── Next.js frontend
├── mobile (github.com/company/mobile)
│   └── React Native
├── shared-types (github.com/company/shared-types)
│   └── npm package
├── api-client (github.com/company/api-client)
│   └── Generated client
├── user-service (github.com/company/user-service)
│   └── Go microservice
└── payment-service (github.com/company/payment-service)
    └── Go microservice

Dependency Management

// web/package.json
{
  "name": "@company/web",
  "dependencies": {
    "@company/shared-types": "^2.4.0",  // Versioned dependency
    "@company/api-client": "^1.8.0"
  }
}

# Update shared-types in web repo
npm install @company/shared-types@latest
git commit -am "chore: update shared-types to 2.5.0"

Git Submodules (Anti-Pattern)

# ❌ AVOID: Git submodules for shared code
git submodule add https://github.com/company/shared-types packages/shared-types

# Problems:
# - Forgotten submodule updates
# - Nested git history complexity
# - CI/CD complications

Better: Publish shared code as npm/pip packages.

Advantages

✅ Pros:

• Team autonomy: Each team owns repo + CI/CD
• Independent releases: Ship frontend without waiting for backend
• Smaller clones: Faster git operations
• Granular access control: Per-repo permissions
• Simpler CI/CD: Smaller build scope
• Clear boundaries: Enforced by repo separation

❌ Cons:

• Version hell: Coordinate shared library updates across repos
• Breaking changes: Update dependency in 10 repos manually
• Duplicate tooling: ESLint config copied across repos
• Slower refactoring: Cross-repo changes need multiple PRs
• Dependency drift: Services on different versions of shared code
• Discovery: Hard to find where code is used

Compare with microservices patterns for service boundaries.

Tooling Landscape

Turborepo (JavaScript/TypeScript)

# Setup
npx create-turbo@latest my-monorepo

# Run commands
turbo run build                    # Build all packages
turbo run test --filter=web        # Test specific package
turbo run build --filter=...[HEAD^1]  # Build changed since last commit

Remote caching:

# Vercel Remote Cache
turbo login
turbo link

# Now CI/CD shares build artifacts
# - Developer builds locally → uploads cache
# - CI pulls cache → skips rebuild

Nx (Full-Stack Monorepo)

# Create Nx workspace
npx create-nx-workspace@latest my-monorepo

# Generate applications
nx g @nx/next:app web
nx g @nx/node:app api

# Run with dependency graph
nx run web:build                   # Auto-builds dependencies
nx affected:test --base=origin/main  # Test affected projects
nx graph                           # Visualize dependencies

Nx Cloud:

# Distributed task execution
nx affected:build --parallel=4
# Tasks distributed across CI agents

Bazel (Google-Scale)

# BUILD.bazel
load("@rules_python//python:defs.bzl", "py_binary")

py_binary(
    name = "api",
    srcs = ["main.py"],
    deps = [
        "//packages/auth:auth_lib",
        "//packages/db:db_lib",
    ],
)

# Build with precise dependency tracking
bazel build //apps/api:api

# Bazel only rebuilds changed targets + dependents
# Supports remote execution (build farm)

Best for: 100K+ files, polyglot monorepos, strict reproducible builds.

Multi-Repo Tooling

# Meta: Manage multiple repos
npm install -g meta

# Clone all repos
meta git clone https://github.com/company/meta.json

# Run command across repos
meta exec "npm install"
meta git status

CI/CD and Build Performance

Monorepo CI/CD (GitHub Actions + Turborepo)

# .github/workflows/ci.yml
name: CI

on:
  push:
    branches: [main]
  pull_request:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0  # Required for turbo --filter

      - uses: pnpm/action-setup@v2
        with:
          version: 8

      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'pnpm'

      - name: Install dependencies
        run: pnpm install

      - name: Build affected packages
        run: pnpm turbo run build --filter=...[origin/main]

      - name: Test affected packages
        run: pnpm turbo run test --filter=...[origin/main]

      - name: Lint
        run: pnpm turbo run lint

Remote Caching with Turborepo

# First build: 120 seconds
turbo run build

# Second build (nothing changed): 0.2 seconds (cache hit)
turbo run build

# CI build: pulls cache from previous run
# Only rebuilds changed packages

Multi-Repo CI/CD (Per-Repo)

# web repo: .github/workflows/ci.yml
name: CI - Web

on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'npm'

      - run: npm ci
      - run: npm run build
      - run: npm test

Cross-repo coordination:

# Trigger downstream repo builds
name: Trigger Dependents

on:
  push:
    branches: [main]
    paths:
      - 'src/**'

jobs:
  trigger:
    runs-on: ubuntu-latest
    steps:
      - name: Trigger web build
        uses: peter-evans/repository-dispatch@v2
        with:
          token: ${{ secrets.REPO_ACCESS_TOKEN }}
          repository: company/web
          event-type: dependency-update

Build Time Comparison

Deploy with Kubernetes platform engineering for containerized builds.

Code Sharing Patterns

Monorepo: Direct Imports

// apps/web/src/pages/index.tsx
import { UserAvatar } from '@company/ui-components';
import { User } from '@company/shared-types';
import { apiClient } from '@company/api-client';

export default function HomePage() {
  const { data } = apiClient.useUser();
  return <UserAvatar user={data} />;
}

Benefits: Always latest version, refactor across packages atomically.

Multi-Repo: Versioned Packages

// package.json
{
  "dependencies": {
    "@company/ui-components": "^2.4.0",
    "@company/shared-types": "^1.8.0"
  }
}

// apps/web/src/pages/index.tsx
import { UserAvatar } from '@company/ui-components';
import { User } from '@company/shared-types';

Benefits: Explicit versioning, gradual updates.

Shared Library Update Flow

Monorepo

# 1. Update shared-types
cd packages/shared-types
# Edit User interface

# 2. Update all consumers in single commit
cd ../../apps/api
# Update User model

cd ../web
# Update frontend usage

# 3. Single atomic commit
git commit -am "feat: add User.email field"
# Everything stays in sync

Multi-Repo

# 1. Update shared-types repo
cd shared-types
# Edit User interface
git commit -am "feat: add User.email field"
git tag v1.9.0
npm publish

# 2. Update api repo
cd ../api
npm install @company/shared-types@1.9.0
# Update User model
git commit -am "feat: add email field"

# 3. Update web repo
cd ../web
npm install @company/shared-types@1.9.0
# Update frontend
git commit -am "feat: display user email"

# Three separate PRs, potentially weeks apart

Dependency Management

Monorepo: Unified Dependencies

// package.json (root)
{
  "name": "my-company",
  "workspaces": ["apps/*", "packages/*"],
  "devDependencies": {
    "typescript": "5.3.3",        // Single version
    "eslint": "8.56.0",
    "prettier": "3.2.0"
  }
}

// apps/web/package.json
{
  "name": "@company/web",
  "dependencies": {
    "react": "18.2.0"            // Workspace hoists dependencies
  }
}

Benefits: Consistent tooling versions, smaller node_modules.

Multi-Repo: Independent Dependencies

// api repo
{
  "devDependencies": {
    "typescript": "5.2.0"        // Different version OK
  }
}

// web repo
{
  "devDependencies": {
    "typescript": "5.3.3"
  }
}

Challenge: Shared library built with TS 5.2, consumer uses TS 5.3 — potential incompatibilities.

Renovate Bot Configuration

// renovate.json (monorepo)
{
  "extends": ["config:base"],
  "groupName": "all dependencies",
  "groupSlug": "all",
  "packageRules": [
    {
      "matchUpdateTypes": ["minor", "patch"],
      "groupName": "all non-major dependencies",
      "automerge": true
    }
  ]
}

Multi-repo: Renovate opens PR in each repo separately — 50 PRs to review vs 1 monorepo PR.

Team Organization

Monorepo Team Patterns

my-company/ (Single monorepo)
├── apps/
│   ├── api/           ← Backend team owns
│   ├── web/           ← Frontend team owns
│   └── mobile/        ← Mobile team owns
├── packages/
│   ├── ui-components/ ← Platform team owns
│   └── shared-types/  ← Shared ownership
└── services/
    ├── user-service/  ← Backend team
    └── payment/       ← Payment team

Code ownership (CODEOWNERS):

# .github/CODEOWNERS
/apps/api/              @company/backend
/apps/web/              @company/frontend
/packages/ui-components/ @company/platform
/services/payment/      @company/payment-team

Multi-Repo Team Patterns

Repos by team:
├── @company/api          ← Backend team owns repo
├── @company/web          ← Frontend team owns repo
├── @company/mobile       ← Mobile team owns repo
├── @company/shared-libs  ← Platform team owns repo
└── @company/payment      ← Payment team owns repo

Access control: Separate repo = separate permissions. More granular than CODEOWNERS.

Migration Strategies

Multi-Repo → Monorepo

# 1. Create monorepo structure
mkdir my-company && cd my-company
pnpm init
pnpm add -D turbo

# 2. Import repos with history
git remote add -f api https://github.com/company/api
git merge --allow-unrelated-histories api/main -X theirs --no-commit
git mv * apps/api/
git commit -m "chore: migrate api to monorepo"

# Repeat for each repo

# 3. Convert to workspace packages
# Update import paths
# Configure Turborepo

Tools:

• tomono: Automates multi-repo → monorepo migration with git history
• splitsh-lite: Reverse (monorepo → multi-repo)

Monorepo → Multi-Repo (Extraction)

# Extract package with history
git subtree split --prefix=packages/auth -b auth-split
cd ../auth-repo
git pull ../my-company auth-split
git push origin main

Scaling Patterns

Monorepo at Scale (Google)

• 2 billion lines of code
• 100K+ engineers
• Single Piper monorepo
• Custom build system (Blaze → Bazel)
• Distributed build execution

Key techniques:

• Sparse checkouts (only clone relevant directories)
• Distributed caching
• Incremental builds
• Virtual file system (FUSE)

Hybrid Pattern (Domain Monorepos)

Company repos:
├── ecommerce-monorepo/     # Product catalog, cart, checkout
├── payments-monorepo/      # Payment processing services
├── data-platform-monorepo/ # Analytics, ML pipelines
└── mobile-apps-monorepo/   # iOS, Android apps

Benefits:

• Monorepo benefits within domain
• Team autonomy across domains
• Clearer service boundaries

Compare with system design patterns for large-scale architectures.

Decision Matrix

By Team Size

By Codebase Characteristics

By Organization

Production Checklist

Monorepo

• Turborepo/Nx configured for incremental builds
• Remote caching enabled (Vercel/Nx Cloud)
• CODEOWNERS file for team ownership
• CI/CD builds only affected packages
• Pre-commit hooks (lint-staged, husky)
• Dependency deduplication verified
• Build times monitored (<10 min target)
• Workspace conventions documented

Multi-Repo

• Shared libraries published to private npm/PyPI
• Semantic versioning enforced
• Changelog automation (conventional commits)
• Renovate/Dependabot configured
• Cross-repo CI triggers set up
• README templates for consistency
• Shared tooling configs (ESLint, Prettier) published
• Dependency update schedule defined

Track with observability dashboards and data pipelines.

Related implementation guides:

• Agent Memory Short Vs Long Term

Primary references: official documentation, official documentation, official documentation, official documentation.

Operating Monorepo vs Multi-Repo as a System

The implementation is only one part of Monorepo vs Multi-Repo. A production design also needs an explicit contract for inputs, outputs, ownership, and failure behavior. Write that contract before selecting a library. It should identify which component validates input, where state lives, what may be retried, and which result is authoritative when two components disagree. This prevents a convenient prototype boundary from silently becoming the long-term architecture.

Start with a representative baseline. Capture request shape, traffic distribution, dependency latency, error classes, and the quality signal users actually care about. Averages hide the cases that cause incidents, so keep percentiles and segment measurements by workload type. Record the configuration and dataset version beside every result. Without that context, a faster or more accurate run cannot be reproduced and should not be used to approve a rollout.

Define the failure model

List failures by where they originate: invalid input, capacity exhaustion, dependency timeout, partial state change, malformed output, and semantically wrong output. Each class needs a different response. Validation errors should fail immediately. Transient dependency failures may be retried with a budget and jitter. An operation that may have committed must use an idempotency key or reconciliation step before retrying. A syntactically valid but incorrect result belongs in evaluation and review, not a blind retry loop.

Set a deadline for the complete operation and derive smaller budgets for each dependency. Local timeouts that add up to more than the caller's deadline merely create abandoned work. Propagate cancellation where the protocol supports it. Bound every queue, retry loop, context buffer, and concurrency pool; an unbounded safety mechanism becomes a second outage during overload.

Design a degraded mode before it is needed. Depending on the workload, that can mean returning a cached answer, selecting a simpler path, placing work in a durable queue, or asking for human review. The degraded response must be visible in telemetry and, where it changes meaning, visible to the caller. Silent fallback makes quality regressions almost impossible to diagnose.

Measure the decision, not just the component

Use three layers of signals. System metrics cover latency, throughput, saturation, and errors. Correctness metrics measure whether the result satisfies its contract. Business or user metrics show whether the system solved the intended problem. Improving only one layer can move the others backward, so release criteria should name acceptable movement for all three.

Attach a reason code to every route, rejection, fallback, and retry. Include version identifiers for configuration, code, model, schema, and data when relevant. Logs should let an engineer reconstruct a decision without storing secrets or raw personal data. Traces should cross process boundaries, while metrics should remain low-cardinality enough to operate reliably.

Alert on symptoms that require action, not every internal anomaly. A useful alert names the affected service objective, links to a runbook, and distinguishes a customer-visible incident from exhausted headroom. Dashboards serve a different purpose: they support diagnosis and capacity planning. Treating a dashboard as an alerting strategy leaves failures undiscovered until someone happens to look.

Roll out with reversible steps

Ship Monorepo vs Multi-Repo behind a versioned interface and a kill switch. Begin with offline replay using production-shaped, privacy-safe samples. Then use shadow execution when duplicate work has acceptable cost and side effects can be suppressed. A small canary should exercise the real dependency graph before traffic expands. Compare the canary with the baseline by cohort rather than mixing both populations into one aggregate.

Promotion gates should be written before the rollout. Include a minimum sample size or observation window, maximum regression in tail latency and error rate, and a correctness threshold. Roll back automatically when a hard safety boundary is crossed; use manual review for ambiguous quality movement. Preserve enough evidence from both paths to explain why the gate passed or failed.

Configuration deserves the same discipline as code. Review changes, validate them before activation, keep an immutable history, and make rollback a single operation. If a deployment changes code and configuration together, record both versions. Otherwise an incident responder may roll back the binary while leaving the triggering configuration active.

Capacity and cost controls

Model capacity in units the bottleneck understands: concurrent connections, tokens, queue jobs, database transactions, GPU memory, or bytes in flight. Convert the expected traffic distribution into those units and include burst behavior. Then load-test the first constrained dependency, not merely the public endpoint. A system that accepts more work than it can finish within its deadline is overloaded even if CPU utilization looks comfortable.

Cost is also a reliability limit. Add per-request attribution, tenant or workflow budgets, and a global circuit breaker for unexpectedly expensive paths. Review unit economics at the same granularity as performance; a cheap median can conceal a small class of requests responsible for most spend. Optimize only after measuring, because reducing context, replicas, validation, or redundancy can trade visible cost for less visible risk.

Production readiness review

Before launch, ask an engineer who did not build the feature to follow the runbook through one simulated failure. Verify backups or checkpoints by restoring them, not by checking that a job reported success. Exercise credential rotation, dependency unavailability, bad configuration, and rollback. Assign an owner for each alarm and a date for reviewing thresholds after real traffic arrives.

The final architecture document should be short enough to remain current. Keep the decision, rejected alternatives, invariants, dependency contracts, dashboards, and rollback procedure. Link detailed experiments rather than pasting them into the document. Teams that need help turning this review into an operable service can use our Monorepo vs Multi-Repo engineering support.

Frequently Asked Questions

Is monorepo only for small teams?

No, Google, Microsoft, and Meta use monorepos with 100K+ engineers. Requires sophisticated tooling (Bazel, custom systems), but scales with proper investment.

Does monorepo slow down CI/CD?

Not with incremental builds. Turborepo/Nx rebuild only changed packages. With remote caching, most CI runs are <1 minute.

How do I control access in a monorepo?

CODEOWNERS for PR approvals, branch protection rules for sensitive directories. True access control requires repo-level separation (multi-repo).

Can I mix monorepo and multi-repo?

Yes, hybrid pattern: monorepo per product domain, multi-repo across domains. Example: payments-monorepo, ecommerce-monorepo as separate repos.

What is the best monorepo tool?

• Turborepo: JavaScript/TypeScript, easiest to adopt
• Nx: Full-stack, powerful but steeper learning curve
• Bazel: Polyglot, Google-scale, complex setup

How do I version packages in a monorepo?

Independent versioning (Lerna, Changesets) or unified versioning (all packages same version). Most monorepos use independent versioning.

Should I use Git submodules for shared code?

No, Git submodules are error-prone. Use npm/pip packages (multi-repo) or workspace packages (monorepo).

Does monorepo work with microservices?

Yes, monorepo contains multiple deployable services. Monorepo is about code organization, not deployment architecture.

Conclusion

Monorepo vs multi-repo is about optimizing for your team's workflow:

• Monorepo for atomic changes, shared code, and fast refactoring
• Multi-repo for team autonomy, independent releases, and access control
• Hybrid (domain monorepos) for large organizations

Most startups and mid-size companies benefit from monorepo with Turborepo/Nx — the tooling has matured significantly.

At HinterBuild, we design repository strategies for scaling engineering teams:

• Backend API Engineering
• Cloud Infrastructure & DevOps
• Kubernetes Platform Engineering
• Data Pipelines & Integrations

Schedule a consultation for monorepo architecture review.