Monorepo Strategy Guide 2025: Nx vs Turborepo vs Lerna — Complete Guide to Managing Large Codebases

Starting a project?
├── Small (fewer than 10 packages)
│   ├── Want quick start → Turborepo
│   └── Need code generation → Nx
├── Medium (10-50 packages)
│   ├── Vercel/Next.js ecosystem → Turborepo
│   ├── Need rich plugins → Nx
│   └── Already using Lerna → Lerna v7
└── Large (50+ packages)
    ├── Need distributed execution → Nx
    └── Microsoft-style → Rush

my-monorepo/
├── pnpm-workspace.yaml
├── package.json
├── .npmrc
├── apps/
│   ├── web/
│   │   └── package.json
│   └── api/
│       └── package.json
├── packages/
│   ├── ui/
│   │   └── package.json
│   ├── utils/
│   │   └── package.json
│   └── config/
│       └── package.json
└── tooling/
    ├── eslint/
    │   └── package.json
    └── typescript/
        └── package.json

packages:
  - "apps/*"
  - "packages/*"
  - "tooling/*"

{
  "name": "my-monorepo",
  "private": true,
  "scripts": {
    "build": "turbo run build",
    "dev": "turbo run dev",
    "lint": "turbo run lint",
    "test": "turbo run test",
    "clean": "turbo run clean"
  },
  "devDependencies": {
    "turbo": "^2.0.0"
  },
  "packageManager": "pnpm@9.0.0"
}

{
  "name": "@myorg/web",
  "dependencies": {
    "@myorg/ui": "workspace:*",
    "@myorg/utils": "workspace:*"
  }
}

# Hoisting settings
shamefully-hoist=false
strict-peer-dependencies=false

# Workspace settings
link-workspace-packages=true
prefer-workspace-packages=true

# Create new Nx workspace
npx create-nx-workspace@latest my-monorepo --preset=ts

# Add Nx to existing monorepo
npx nx@latest init

{
  "targetDefaults": {
    "build": {
      "dependsOn": ["^build"],
      "inputs": ["production", "^production"],
      "cache": true
    },
    "test": {
      "inputs": ["default", "^production"],
      "cache": true
    },
    "lint": {
      "inputs": ["default", "{workspaceRoot}/.eslintrc.json"],
      "cache": true
    }
  },
  "namedInputs": {
    "default": ["{projectRoot}/**/*", "sharedGlobals"],
    "production": [
      "default",
      "!{projectRoot}/**/*.spec.ts",
      "!{projectRoot}/tsconfig.spec.json"
    ],
    "sharedGlobals": ["{workspaceRoot}/tsconfig.base.json"]
  },
  "nxCloudAccessToken": "your-token-here"
}

# Visualize project dependency graph
npx nx graph

# Focus on a specific project
npx nx graph --focus=my-app

# View affected projects
npx nx affected:graph

Project graph example:

    web-app ───▶ ui-lib ───▶ utils
       │            │
       ▼            ▼
    api-app ───▶ shared-types

# Build only projects affected by changes
npx nx affected -t build

# Test only affected projects
npx nx affected -t test

# Specify base branch
npx nx affected -t build --base=main --head=HEAD

# Generate React component
npx nx generate @nx/react:component Button --project=ui

# Generate library
npx nx generate @nx/js:library shared-utils

# Create custom generator
npx nx generate @nx/plugin:generator my-generator --project=tools

# Connect to Nx Cloud
npx nx connect

# CI configuration with Nx
name: CI
on: [push]
jobs:
  main:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: pnpm/action-setup@v2
      - uses: actions/setup-node@v4
      - run: pnpm install --frozen-lockfile
      - uses: nrwl/nx-set-shas@v4
      - run: npx nx affected -t lint test build

# Create new Turborepo project
npx create-turbo@latest

# Add Turborepo to existing monorepo
pnpm add -D turbo -w

{
  "$schema": "https://turbo.build/schema.json",
  "globalDependencies": ["**/.env.*local"],
  "globalEnv": ["NODE_ENV"],
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "inputs": ["$TURBO_DEFAULT$", ".env*"],
      "outputs": ["dist/**", ".next/**", "!.next/cache/**"],
      "env": ["DATABASE_URL"]
    },
    "test": {
      "dependsOn": ["build"],
      "inputs": ["$TURBO_DEFAULT$"],
      "outputs": ["coverage/**"]
    },
    "lint": {
      "dependsOn": ["^build"],
      "cache": true
    },
    "dev": {
      "cache": false,
      "persistent": true
    },
    "clean": {
      "cache": false
    }
  }
}

When running turbo run build:

1. Dependency graph analysis
   utils (no deps) → ui (depends on utils) → web (depends on ui, utils)

2. Parallel execution
   [utils: build] ──done──▶ [ui: build] ──done──▶ [web: build]
                            [api: build] ──────────┘
                              (depends only on utils)

3. Caching
   - Calculate hash of input files
   - If hash matches previous build, restore from cache
   - Build time: 5min → 0.1sec (cache hit)

# Local cache location
ls node_modules/.cache/turbo/

# Check cache status
turbo run build --dry-run

# Invalidate cache
turbo run build --force

# Enable remote caching
npx turbo login
npx turbo link

# Build specific package only
turbo run build --filter=@myorg/web

# Build only changed packages
turbo run build --filter=...[HEAD^1]

# Build specific package and its dependencies
turbo run build --filter=@myorg/web...

# Packages in a specific directory
turbo run build --filter=./apps/*

# Vercel Remote Cache (official)
npx turbo login
npx turbo link

TURBO_TOKEN=your-token
TURBO_TEAM=your-team
TURBO_API=https://your-cache-server.com

packages/
├── ui/              # UI components (Button, Modal, Form)
├── utils/           # Utilities (date, string, validation)
├── types/           # Shared TypeScript types
├── config/          # Shared config (ESLint, TypeScript, Prettier)
├── hooks/           # Shared React hooks
├── api-client/      # API client (type-safe fetch)
└── constants/       # Constants (error codes, route paths)

{
  "name": "@myorg/ui",
  "private": true,
  "main": "./src/index.ts",
  "types": "./src/index.ts",
  "exports": {
    ".": "./src/index.ts",
    "./*": "./src/*.ts"
  }
}

{
  "compilerOptions": {
    "paths": {
      "@myorg/ui": ["../../packages/ui/src"],
      "@myorg/ui/*": ["../../packages/ui/src/*"]
    }
  }
}

{
  "name": "@myorg/utils",
  "version": "1.0.0",
  "main": "./dist/index.js",
  "module": "./dist/index.mjs",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "import": "./dist/index.mjs",
      "require": "./dist/index.js",
      "types": "./dist/index.d.ts"
    }
  },
  "scripts": {
    "build": "tsup src/index.ts --format esm,cjs --dts"
  }
}

# Installation
pnpm add -D @changesets/cli -w

# Initialize
pnpm changeset init

# 1. Add change description
pnpm changeset
# ? Which packages changed? → @myorg/ui, @myorg/utils
# ? Change type? → minor (new feature)
# ? Description? → Added new Button variant

# 2. File created in .changeset/ directory
cat .changeset/brave-dogs-run.md
# ---
# "@myorg/ui": minor
# "@myorg/utils": patch
# ---
#
# Added new Button variant

# 3. Version update (run in CI)
pnpm changeset version

# 4. Publish
pnpm changeset publish

{
  "$schema": "https://unpkg.com/@changesets/config@3.0.0/schema.json",
  "changelog": "@changesets/cli/changelog",
  "commit": false,
  "fixed": [],
  "linked": [["@myorg/ui", "@myorg/hooks"]],
  "access": "restricted",
  "baseBranch": "main",
  "updateInternalDependencies": "patch",
  "ignore": ["@myorg/web", "@myorg/api"]
}

# .github/workflows/ci.yml
name: CI
on:
  pull_request:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

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

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

      - run: pnpm install --frozen-lockfile

      # Turborepo: build only changed packages
      - run: turbo run build test lint --filter=...[origin/main]

      # Or Nx: affected projects only
      # - run: npx nx affected -t build test lint

Without cache:
  lint (2min) + test (5min) + build (8min) = 15min

Remote cache hit:
  lint (0.1s) + test (0.2s) + build (0.3s) = 0.6s

Only actually changed packages:
  lint (20s) + test (1min) + build (2min) = 3min 20s

# Matrix strategy for parallel execution
jobs:
  detect:
    runs-on: ubuntu-latest
    outputs:
      packages: ${{ steps.filter.outputs.packages }}
    steps:
      - uses: actions/checkout@v4
      - id: filter
        run: echo "packages=$(turbo run build --filter=...[origin/main] --dry-run=json | jq -c '.packages')" >> $GITHUB_OUTPUT

  build:
    needs: detect
    runs-on: ubuntu-latest
    strategy:
      matrix:
        package: ${{ fromJson(needs.detect.outputs.packages) }}
    steps:
      - uses: actions/checkout@v4
      - run: turbo run build --filter=${{ matrix.package }}

# Docker build in a monorepo
FROM node:20-slim AS base
RUN corepack enable

FROM base AS pruned
WORKDIR /app
COPY . .
# turbo prune: extract specific app and its dependencies
RUN npx turbo prune @myorg/api --docker

FROM base AS installer
WORKDIR /app
# Install dependencies first (cache layer)
COPY --from=pruned /app/out/json/ .
COPY --from=pruned /app/out/pnpm-lock.yaml ./pnpm-lock.yaml
RUN pnpm install --frozen-lockfile

# Copy source and build
COPY --from=pruned /app/out/full/ .
RUN pnpm turbo run build --filter=@myorg/api

FROM base AS runner
WORKDIR /app
COPY --from=installer /app/apps/api/dist ./dist
COPY --from=installer /app/node_modules ./node_modules
CMD ["node", "dist/main.js"]

# .github/CODEOWNERS

# Global default owners
* @org/platform-team

# App-specific owners
/apps/web/          @org/frontend-team
/apps/api/          @org/backend-team
/apps/mobile/       @org/mobile-team

# Package-specific owners
/packages/ui/       @org/design-system-team
/packages/utils/    @org/platform-team
/packages/auth/     @org/security-team

# Configuration files
/tooling/           @org/dx-team
/.github/           @org/dx-team
/turbo.json         @org/dx-team

// .eslintrc.json
{
  "rules": {
    "@nx/enforce-module-boundaries": [
      "error",
      {
        "depConstraints": [
          {
            "sourceTag": "scope:web",
            "onlyDependOnLibsWithTags": ["scope:shared", "scope:web"]
          },
          {
            "sourceTag": "scope:api",
            "onlyDependOnLibsWithTags": ["scope:shared", "scope:api"]
          },
          {
            "sourceTag": "type:app",
            "onlyDependOnLibsWithTags": ["type:lib", "type:util"]
          },
          {
            "sourceTag": "type:lib",
            "onlyDependOnLibsWithTags": ["type:lib", "type:util"]
          }
        ]
      }
    ]
  }
}

# Create new monorepo repository
mkdir my-monorepo && cd my-monorepo
git init
pnpm init

# Move existing repo as subdirectory (preserving history)
git remote add -f web-repo https://github.com/org/web-app.git
git merge web-repo/main --allow-unrelated-histories

# Restructure directory using git-filter-repo
git filter-repo --to-subdirectory-filter apps/web

# Set up pnpm workspace
cat > pnpm-workspace.yaml << 'EOF'
packages:
  - "apps/*"
  - "packages/*"
EOF

# Extract duplicate code into shared packages
mkdir -p packages/shared-utils/src
# Move common utilities and configure packages

# Set up Turborepo or Nx
pnpm add -D turbo -w
# Configure turbo.json (see section 6.2)

# Before: build all packages (15min)
pnpm -r run build

# After: only changed packages (2min)
turbo run build --filter=...[origin/main]

# Check dependency version mismatches with syncpack
npx syncpack list-mismatches
npx syncpack fix-mismatches

# Shallow clone
git clone --depth 1 https://github.com/org/monorepo.git

# Partial clone (without blobs)
git clone --filter=blob:none https://github.com/org/monorepo.git

# Sparse checkout (specific directories only)
git clone --sparse https://github.com/org/monorepo.git
cd monorepo
git sparse-checkout set apps/web packages/ui

{
  "tasks": {
    "build": {
      "dependsOn": ["^build"]
    }
  }
}