Monorepo Tools

Decision Framework

When to Choose Each

Turborepo (default choice for JS/TS):

• <50 packages
• Team already uses Vercel
• Need fast setup with minimal config
• No need for architecture enforcement
• turbo.json pipeline config is all you need

Nx (when you need guardrails):

• Need module boundary enforcement (@nx/enforce-module-boundaries)
• Want code generators for consistent project scaffolding
• Plugin ecosystem matters (React, Angular, Node have first-class support)
• Team is growing and you need architectural constraints

Bazel (when scale demands it):

• Polyglot codebase (JS + Python + Go + Java)

• 100 packages / >500 engineers

• Need hermetic, reproducible builds
• Need remote execution (distribute builds across machines)
• Willing to invest in build infrastructure team

Migration Path

Turborepo -> Nx (when you need boundaries) -> Bazel (when Nx can't scale)

Core Concepts

Task graph: DAG of build tasks. ^build = build dependencies first. Tools traverse this for parallelism and caching.

Caching: Hash inputs (source files, env vars, configs) -> cache key -> store outputs. Cache hit = skip execution. All tools support local + remote cache.

Affected detection: Compare current state to base branch. Run only tasks for changed packages and their dependents. Critical for CI speed.

Turborepo Key Opinions

Pipeline Configuration

• Always specify inputs -- default hashes everything, including test files for build tasks
• Set outputs precisely -- ["dist/**"] not ["dist"]
• env must list all env vars that affect output -- missing one = stale cache
• "dev": { "cache": false, "persistent": true } -- dev servers are never cacheable

Filtering

turbo build --filter='...[origin/main]'  # Changed since main (CI)
turbo build --filter=@myorg/web...       # Package + its dependencies
turbo build --filter='./apps/*'          # By directory

Cache Debugging

turbo build --dry-run          # What would run
turbo build --summarize        # Cache hit/miss stats
turbo build --force            # Skip cache entirely

Nx Key Opinions

Library Types (enforce via tags)

This hierarchy prevents circular dependencies and enforces separation of concerns.

Scope Tags

Add scope:web, scope:api, scope:shared to prevent cross-platform leaks.

Shared Patterns

TypeScript Config

• Single tsconfig.base.json at root with shared compilerOptions
• Per-project tsconfig.json extends base, adds rootDir/outDir
• Use "moduleResolution": "bundler" for modern projects

Package Exports

{
  "exports": {
    ".": { "import": "./dist/index.js", "types": "./dist/index.d.ts" },
    "./button": { "import": "./dist/button.js", "types": "./dist/button.d.ts" }
  }
}

• Always include types condition
• Use granular exports, not barrel files with everything

Dependency Management (pnpm preferred)

• pnpm workspaces for JS/TS monorepos -- strict, fast, disk-efficient
• pnpm add react --filter @repo/ui -- add to specific package
• Use catalog: in pnpm-workspace.yaml to pin shared dependency versions

Changesets for Publishing

• @changesets/cli for version management and npm publishing
• Changeset per PR -- enforced via CI check
• Auto-merge minor/patch updates, manual review for major