Turborepo Monorepo

Commands

Running Tasks

turbo run build                    # Build all packages
turbo run test                     # Test all packages
turbo run lint                     # Lint all packages
turbo run build --filter=web       # Build specific package
turbo run build --filter=./apps/*  # Build all apps
turbo run build --filter=...[HEAD~1]  # Only affected since last commit

Common Patterns

turbo run build test lint          # Run multiple tasks
turbo run build --dry-run          # Preview what would run
turbo run build --graph            # Visualize task graph
turbo run build --force            # Ignore cache, rebuild all
turbo run build --concurrency=4    # Limit parallelism

Forbidden Commands

# NEVER use these directly — always go through turbo:
npm run build      # Skips caching and parallelism
cd apps/web && npm test  # Skips dependency resolution

Pipeline Configuration (turbo.json)

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

Key Concepts

• ^build — run build in dependencies first (topological)
• dependsOn — declare task dependencies
• outputs — files to cache (miss = rebuild)
• inputs — files to hash for cache key (default: all tracked files)
• cache: false — never cache (use for dev, start)
• persistent: true — long-running tasks (dev servers)

Caching

Local Cache

Turborepo caches task outputs automatically in node_modules/.cache/turbo. Cache keys are computed from:

1. Task inputs (source files)
2. Environment variables
3. Dependencies' build outputs
4. turbo.json configuration

Remote Cache

turbo login                        # Authenticate
turbo link                         # Link project to remote cache
turbo run build --remote-only      # Force remote cache usage

• Shares cache across CI and team members
• Vercel Remote Cache or self-hosted (Ducktape, TurboCache)
• Set TURBO_TOKEN and TURBO_TEAM in CI environment

Quick Workflow: Setup remote caching in CI

1. Add TURBO_TOKEN and TURBO_TEAM to your CI secrets.
2. Locally run turbo login and turbo link to verify the project is linked.
3. Add turbo run build --remote to the CI pipeline and watch for cache hit/miss logs.
4. If cache misses persist: verify inputs/outputs in turbo.json, stable env vars, then re-run.

Validation (recommended): run turbo run build --dry-run locally or in CI to preview the task graph and catch misconfigured inputs/outputs before executing.

See REFERENCE.md for CI snippets and advanced cache tuning.

Package Workspace Structure

monorepo/
├── turbo.json
├── package.json              # Root workspace config
├── apps/
│   ├── web/                  # Next.js app
│   └── docs/                 # Documentation site
├── packages/
│   ├── ui/                   # Shared UI components
│   ├── config/               # Shared config (ESLint, TS)
│   └── utils/                # Shared utilities

Best Practices

• Always use turbo run instead of directly invoking package scripts
• Define outputs for every cacheable task — missing outputs mean missing cache
• Use --filter to scope commands to affected packages
• Set inputs to narrow cache keys and avoid unnecessary rebuilds
• Use --dry-run to debug pipeline configuration
• Add TURBO_TOKEN and TURBO_TEAM to CI for remote caching
• Never commit .turbo/ or node_modules/.cache/turbo

Further reading: see REFERENCE.md in this directory for CI snippets and advanced cache tuning.