Introduction

A monorepo puts all your packages, apps, and libraries in a single Git repository. The promise is compelling: atomic commits across packages, simplified dependency management, and unified tooling. The reality is that monorepos can become unbearably slow without the right tooling — every CI run builds everything, every test suite runs everything, and every deploy ships everything.

Enter Nx and Turborepo. These tools understand the dependency graph between your packages and use Git to determine what actually changed. Instead of rebuilding the entire repository, they compute the “affected” set — only the packages that changed or depend on changed packages. Combined with remote caching, they make monorepos faster than separate repositories.

This post covers how Nx and Turborepo integrate with Git, how affected builds work, caching strategies, and production patterns for monorepo management. Whether you’re managing 5 packages or 500, these tools are essential for monorepo success.

When to Use / When Not to Use

Use monorepo tools when:

• You have multiple packages that share dependencies
• You need atomic commits across packages
• Your CI pipeline is slow from building everything
• You want unified tooling and standards
• You need to track cross-package changes

Avoid monorepo tools when:

• You have a single package or app
• Your packages are truly independent
• Your team can’t handle the tooling complexity
• You need separate deployment pipelines per package

Core Concepts

Monorepo tools work by building a dependency graph and using Git to detect changes:

flowchart TD
    A[Git Push] --> B[Detect Changed Files]
    B --> C[Map Files to Packages]
    C --> D[Build Dependency Graph]
    D --> E[Compute Affected Set]
    E --> F{Cached?}
    F -->|Yes| G[Use Cache]
    F -->|No| H[Build Package]
    G --> I[Aggregate Results]
    H --> I
    I --> J[Deploy Affected]

Architecture and Flow Diagram

sequenceDiagram
    participant Dev as Developer
    participant Git as Git Repository
    participant Tool as Nx/Turborepo
    participant Graph as Dependency Graph
    participant Cache as Remote Cache
    participant CI as CI Pipeline

    Dev->>Git: Push changes
    Git->>Tool: Trigger pipeline
    Tool->>Git: git diff --name-only HEAD~1
    Git-->>Tool: Changed files
    Tool->>Graph: Map files to packages
    Graph->>Graph: Compute affected packages
    Graph-->>Tool: Affected set
    Tool->>Cache: Check cache for each package
    Cache-->>Tool: Cache hits/misses
    Tool->>CI: Build only cache misses
    CI-->>Tool: Build results
    Tool->>Cache: Store new results
    Tool-->>Dev: Pipeline complete

Step-by-Step Guide

1. Nx Setup

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

# Or add to existing repo
npx nx@latest init

Project configuration:

// nx.json
{
  "targetDefaults": {
    "build": {
      "dependsOn": ["^build"],
      "cache": true
    },
    "test": {
      "dependsOn": ["build"],
      "cache": true
    },
    "lint": {
      "cache": true
    }
  },
  "defaultBase": "main"
}

Affected builds:

# Run tests only for affected packages
nx affected:test

# Build affected packages and their dependencies
nx affected:build

# See what would be affected
nx affected --base=main --head=HEAD

# Run with parallelism
nx affected:test --parallel=4

2. Turborepo Setup

# Initialize Turborepo
npx turbo init

# Or add to existing workspace
npm install turbo --save-dev

Pipeline configuration:

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

Running tasks:

# Run build for all packages
turbo run build

# Run only for changed packages
turbo run build --filter="...[origin/main]"

# Run with concurrency
turbo run build --concurrency=4

# Dry run to see what would execute
turbo run build --dry-run

3. Git Integration Patterns

Nx with Git:

# Compare against main branch
nx affected --base=main

# Compare against last successful build
nx affected --base=HEAD~1

# Custom range
nx affected --base=v1.0.0 --head=v1.1.0

Turborepo with Git:

# Filter by changed packages since main
turbo run build --filter="...[origin/main]"

# Filter specific package
turbo run build --filter=my-package

# Filter by tag
turbo run build --filter="...[HEAD~1]"

4. Remote Caching Setup

Nx Cloud:

npx nx connect
# Sets up NX_CLOUD_ACCESS_TOKEN

Turborepo Remote Cache:

# Use Vercel Remote Cache
turbo login
turbo link

# Or self-hosted
turbo run build --remote-cache=http://cache.internal:3000

5. CI Configuration

# GitHub Actions with Nx
name: CI
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
jobs:
  ci:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npx nx affected -t lint test build --parallel=3
        env:
          NX_CLOUD_ACCESS_TOKEN: ${{ secrets.NX_CLOUD_ACCESS_TOKEN }}

Production Failure Scenarios

Scenario	Impact	Mitigation
Cache corruption	Wrong results served	Clear cache; use cache versioning
Dependency graph incorrect	Missed affected packages	Run nx reset or turbo prune
Remote cache unavailable	Falls back to local	Configure local cache fallback
Large monorepo performance	Slow graph computation	Use sparse checkout; optimize workspace
CI fetch-depth too shallow	Can’t compute affected	Use fetch-depth: 0 in CI

Trade-off Analysis

Aspect	Nx	Turborepo
Learning curve	Steeper	Gentler
Plugin ecosystem	Rich	Growing
Language support	Multi-language	Primarily JS/TS
Caching	Nx Cloud	Vercel/Self-hosted
Configuration	More complex	Simpler
Best for	Enterprise monorepos	JS/TS monorepos

Implementation Snippets

Nx workspace with affected deployment:

# Deploy only affected apps
nx affected --target=deploy --base=main --parallel=1

Turborepo with package filtering:

# Build package and its dependencies
turbo run build --filter=my-package^...

# Build everything except specific package
turbo run build --filter=!my-package

Custom affected detection script:

#!/bin/bash
# scripts/affected-check.sh
BASE=${1:-main}
AFFECTED=$(git diff --name-only $BASE HEAD | grep -oP 'packages/[^/]+' | sort -u)
echo "Affected packages: $AFFECTED"
for pkg in $AFFECTED; do
  echo "Testing $pkg..."
  cd $pkg && npm test
done

Observability Checklist

• Logs: Log affected package computation and cache hit rates
• Metrics: Track build time savings from affected builds
• Alerts: Alert on cache misses and graph computation failures
• Dashboards: Monitor monorepo health and build performance
• Traces: Trace file changes through dependency graph to builds

Security & Compliance Considerations

• Remote cache may store build artifacts; ensure encryption
• CI tokens for cache access should be scoped and rotated
• For regulated environments, audit cache contents
• Use workspace boundaries to isolate sensitive packages
• Version cache keys to prevent stale artifact serving

Common Pitfalls / Anti-Patterns

Anti-Pattern	Why It’s Bad	Fix
Not configuring cache outputs	Cache misses on every run	Define outputs in turbo.json/nx.json
Ignoring dependency graph	Wrong affected computation	Validate graph regularly
Shallow clone in CI	Can’t compute affected	Use fetch-depth: 0
No cache eviction policy	Cache grows indefinitely	Set cache limits and TTL
Mixing package managers	Inconsistent resolution	Use workspaces consistently

Quick Recap Checklist

• Choose Nx or Turborepo based on needs
• Configure pipeline with proper inputs/outputs
• Set up remote caching
• Configure CI with affected builds
• Validate dependency graph accuracy
• Monitor cache hit rates
• Document workspace structure
• Set up cache eviction policies

Extended Architecture Diagram

flowchart TD
    subgraph "Git Repository"
        A[packages/ui] --> B[packages/api]
        A --> C[apps/web]
        B --> C
        B --> D[apps/admin]
    end

    subgraph "Change Detection"
        E[git diff --name-only] --> F{Changed Files}
        F --> G[Map to packages/ui]
        F --> H[Map to packages/api]
    end

    subgraph "Dependency Graph"
        G --> I[apps/web depends on ui]
        G --> J[apps/admin depends on api]
        H --> J
        H --> I
    end

    subgraph "Affected Set"
        I --> K[Build ui, api, web, admin]
        J --> K
    end

    subgraph "Cache Layer"
        K --> L{Cache Hit?}
        L -->|Yes| M[Download artifacts]
        L -->|No| N[Build and cache]
    end

Extended Production Failure Scenario

Incorrect Affected Calculation Causing Skipped Builds

A developer changes a shared utility function in packages/utils/src/helpers.ts. The monorepo tool’s dependency graph is stale because package.json wasn’t updated — the utility is imported directly without being declared as a dependency. The affected calculation misses apps/web which imports the helper. The CI skips building apps/web, the change deploys without testing, and production breaks with a runtime error.

Why the graph goes stale: Both Nx and Turborepo build their dependency graphs from project.json/workspace.json and package.json declarations. They do not scan import statements at runtime. If a developer imports a file without adding it to dependencies, the graph has no way to know about that relationship. This is the most common root cause behind incorrect affected calculations.

Concrete example of the failure chain:

# Developer adds import but forgets to declare dependency
# packages/utils/src/helpers.ts
export function formatDate(date: Date): string { ... }

# packages/web/src/components/DateDisplay.tsx
import { formatDate } from '@company/utils/src/helpers'; # WRONG — uses internal path
# package.json in packages/web does NOT list @company/utils as dependency

Nx/Turborepo never sees this import because it is not a package-level declaration. When the developer runs nx affected --base=main, packages/web does not appear in the affected set, even though formatDate changed.

How to detect this before it reaches CI:

# Nx: visualize the actual project graph
npx nx graph

# Turborepo: dry-run shows what would execute
turbo run build --dry-run

# Check for undeclared dependencies with madge
npx madge --circular --extensions ts packages/web/src

Mitigation: Add a CI step that statically analyzes import statements and compares them against declared package dependencies. Tools like dependency-cruiser or madge do this. Fail the build if actual imports go beyond what package.json declares. For Nx, run nx reset to clear the cached graph whenever project structure changes. For Turborepo, use turbo run build --force to bypass the cache and force a fresh graph computation when in doubt. On top of that, enforce import boundaries via ESLint rules like import/no-unresolved to catch cross-package imports that bypass package boundaries.

Extended Trade-offs

Aspect	Nx	Turborepo	Lerna	Bazel
Build speed	Fast with caching	Very fast — Rust core	Slow — no native caching	Fastest — distributed
Language support	Multi-language (JS, Python, Go, etc.)	Primarily JS/TS	JS/TS only	Any language
Complexity	High — many concepts	Low — simple pipeline config	Medium — legacy tooling	Very high — steep learning curve
Ecosystem	Rich plugin system	Growing, Vercel-backed	Declining — superseded by Turborepo	Enterprise-grade
Best for	Large enterprise monorepos	JS/TS teams wanting simplicity	Legacy projects	Polyglot, massive scale

Extended Observability Checklist

Monorepo Git Metrics

A monorepo that scales gracefully and one that gradually turns into an unmaintainable tangle often look identical in the first six months. The difference shows up in what you measure. These seven metrics give you early warning signals before problems become crises.

Affected scope — Number of packages affected per PR. This is your most direct measure of coupling. Track the rolling average over the last 20 PRs. A sudden jump from a baseline of 3-5 packages to 15+ packages in a single PR is a red flag. It usually means someone accidentally changed a widely-imported file or introduced a new cross-package dependency. Set a threshold alert: if a PR affects more than 20% of the workspace, require a second reviewer.

Build cache hit rate — Percentage of builds served from cache. Target: above 70% for local builds, above 60% for CI. Below 50% means your cache keys are unstable or your inputs are too broad. Common causes: including package-lock.json in inputs (it changes on every npm install), environment variables that vary per run, or timestamps in source files. Run turbo run build --dry-run to inspect which inputs are contributing to the hash.

PR size vs. affected count — Calculate affected_packages / changed_files. In a well-structured monorepo this ratio is close to 1. A ratio above 2 means a single file change is cascading through many packages, which signals tight coupling. Watch this ratio over time; a gradually increasing trend means the dependency graph is getting deeper without anyone intervening.

Dependency graph depth — The longest chain from leaf package to root app. Measure it with nx graph --output=json | jq '[.nodes[].data.implicitDeps] | max_by(length)' or the Turborepo visualizer. Depth above 5 is a warning sign; above 8 is critical. Deep chains amplify the blast radius of every change. If depth is growing, consider extracting shared utilities into flatter intermediate packages rather than letting every app import from a single monolithic packages/core.

Build time per package — Identify your top5 slowest packages by average build time. These become CI bottlenecks. For each slow package, check whether it is doing work that could be cached or whether it has unnecessary build dependencies. A package that takes more than 5 minutes to build should get its own dedicated CI runner in a parallel job matrix.

Cache storage growth — Remote caches grow unbounded without policies. Monitor growth weekly. For Turborepo, set a cache size limit with --remote-cache-size=10gb. For Nx Cloud, configure retention policies. If your cache grows more than 20% week-over-week without adding new packages, you probably have artifact bloat from packages that declare too many output globs.

Cross-package coupling — Measure how often changes in one package force rebuilds in others. One practical approach: label every package pair that appears together in affected sets over a 30-day window. If package A and package B always appear together, they are effectively one unit. Consider merging them. High coupling across many packages is a reliable indicator that your monorepo is starting to behave like a monolith — and monoliths eventually lose the ability to do targeted affected-based builds.

Cross-Roadmap References

• System Design Learning Roadmap — Broader system architecture context for monorepo scaling decisions
• Microservices Architecture — System Design roadmap: service-level dependency patterns

Interview Questions

Further Reading

• Nx Documentation
• Turborepo Documentation
• Changesets for Versioning
• Monorepo Tools Comparison
• Remote Cache Setup

Conclusion

Monorepos push Git to its limits with thousands of files and hundreds of packages. Tools like Nx and Turborepo leverage Git’s change detection to run only the affected tasks — they don’t replace Git but layer on top of it, making large repositories as fast to work with as small ones.