Turborepo

Turborepo

Build system for JavaScript/TypeScript monorepos. Handles task orchestration, caching, and dependency-aware execution across workspaces.

Setup

# New monorepo
npx create-turbo@latest my-monorepo

# Add to existing repo
pnpm add turbo --save-dev --workspace-root
# or: npm install turbo --save-dev

Add .turbo to .gitignore. Add root scripts:

{
  "scripts": {
    "build": "turbo run build",
    "dev": "turbo run dev",
    "test": "turbo run test",
    "lint": "turbo run lint"
  }
}

turbo.json Configuration

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

• dependsOn -- tasks that must complete first. ^ prefix = topological (upstream workspaces).
• outputs -- files produced by the task, used for caching.
• cache -- set false to disable caching.
• persistent -- marks long-running tasks (dev servers).
• env -- environment variables that affect the task hash.

Turborepo v2 uses "tasks" instead of the v1 "pipeline" key.

Workspace Structure

my-monorepo/
  turbo.json
  package.json
  pnpm-workspace.yaml
  apps/
    web/package.json
    api/package.json
  packages/
    ui/package.json
    shared-types/package.json
    eslint-config/package.json
    tsconfig/package.json

Task Orchestration

turbo run build                    # all workspaces
turbo run lint build test          # multiple tasks
turbo run build --concurrency=4    # limit parallelism
turbo run build --concurrency=50%  # percentage of CPU cores

Turbo analyzes the dependency graph and parallelizes where possible.

Task Dependencies

"^build" means run build in all upstream workspace dependencies first. If apps/web depends on packages/ui, then packages/ui#build runs before apps/web#build.

"lint" (no caret) means run lint in the same workspace first:

{ "test": { "dependsOn": ["lint", "build"] } }

Per-workspace overrides -- add a turbo.json in the workspace directory:

{
  "extends": ["//"],
  "tasks": { "build": { "outputs": [".next/**"] } }
}

Caching

Turbo hashes inputs (source files, deps, env vars, config) and caches task outputs. On a cache hit, outputs are restored and logs replayed without re-execution.

turbo run build --no-cache   # skip reading cache
turbo run build --force      # ignore cache, re-execute all

Remote caching

npx turbo login
npx turbo link

Connects to Vercel for shared remote caching across team members and CI.

Self-hosted endpoint:

turbo run build --api="https://cache.example.com" --token="<token>"

Environment Variables

{
  "tasks": {
    "build": {
      "env": ["API_URL", "DATABASE_URL"],
      "passThroughEnv": ["AWS_SECRET_ACCESS_KEY"]
    }
  },
  "globalEnv": ["CI", "VERCEL"]
}

• env -- affects this task's cache hash.
• globalEnv -- affects all tasks' cache hashes.
• passThroughEnv -- passed to task but excluded from hash (for secrets).

Filtering

turbo run build --filter=web                    # by workspace name
turbo run build --filter=@myorg/ui              # by package name
turbo run test --filter=./apps/*                # by path glob
turbo run build --filter=...@myorg/ui           # package and its dependents
turbo run build --filter=@myorg/ui...           # package and its dependencies
turbo run build --filter=...[HEAD~1]            # changed since last commit
turbo run test --filter=...[main...HEAD]        # changed vs main branch
turbo run build --filter=./apps/* --filter=!./apps/admin  # exclude

Shared Packages

Internal UI library

packages/ui/package.json:

{
  "name": "@myorg/ui",
  "main": "./src/index.ts",
  "types": "./src/index.ts",
  "scripts": {
    "build": "tsup src/index.ts --format esm,cjs --dts",
    "lint": "eslint src/"
  }
}

Consume with "@myorg/ui": "workspace:*" in the app's dependencies. For internal packages transpiled by the consuming bundler, point main at TypeScript source and skip the build step.

Shared TypeScript config

packages/tsconfig/base.json:

{
  "compilerOptions": {
    "strict": true, "target": "ES2020", "module": "ESNext",
    "moduleResolution": "bundler", "declaration": true,
    "esModuleInterop": true, "skipLibCheck": true
  }
}

Reference: { "extends": "@myorg/tsconfig/base.json", "include": ["src"] }

Shared types

packages/shared-types/package.json -- set "main" and "types" to "./src/index.ts". No build step needed if consumers transpile directly.

pnpm Workspaces Integration

pnpm-workspace.yaml:

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

Use workspace:* protocol for internal deps. For npm workspaces, use the "workspaces" field in root package.json instead.

Watch Mode

turbo watch dev
turbo watch build

Watches for file changes, re-runs affected tasks respecting the dependency graph. Shared package changes trigger downstream rebuilds.

Pruning for Docker

turbo prune web --docker

Produces out/json/ (pruned package.json files for install layer) and out/full/ (pruned source).

FROM node:20-alpine AS builder
RUN corepack enable
WORKDIR /app
COPY . .
RUN turbo prune web --docker

FROM node:20-alpine AS installer
RUN corepack enable
WORKDIR /app
COPY --from=builder /app/out/json/ .
RUN pnpm install --frozen-lockfile
COPY --from=builder /app/out/full/ .
RUN turbo run build --filter=web

FROM node:20-alpine AS runner
WORKDIR /app
COPY --from=installer /app/apps/web/.next/standalone ./
CMD ["node", "apps/web/server.js"]

CI/CD Patterns

GitHub Actions with remote cache

name: CI
on: [push, pull_request]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v4
      - uses: actions/setup-node@v4
        with: { node-version: 20, cache: pnpm }
      - run: pnpm install --frozen-lockfile
      - run: turbo run build test lint
        env:
          TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
          TURBO_TEAM: ${{ vars.TURBO_TEAM }}

Run only affected tasks: turbo run build test --filter=...[origin/main...HEAD]

Use turbo run build --dry-run=json to get the task graph for dispatching parallel CI jobs per workspace.

Migration from Lerna or Nx

From Lerna

1. Remove lerna.json and lerna dependency.
2. Keep workspace config (package.json workspaces or pnpm-workspace.yaml).
3. Create turbo.json with task definitions matching Lerna scripts.
4. Replace lerna run build with turbo run build.
5. Replace lerna run test --scope=pkg with turbo run test --filter=pkg.

From Nx

1. Remove nx.json, project.json files, and nx dependencies.
2. Move task config from project.json targets into turbo.json tasks.
3. Replace nx run-many -t build with turbo run build.
4. Replace nx affected -t test with turbo run test --filter=...[origin/main...HEAD].

Differences: Nx uses per-project project.json and its own dependency analysis; Turbo uses a single root turbo.json and relies on the package manager's workspace graph. Nx has generators/executors; Turbo delegates to workspace package.json scripts.

Troubleshooting

turbo run build --dry-run       # show what would run
turbo run build --graph         # output task graph (DOT format)
turbo run build --summarize     # generate run summary JSON
turbo ls                        # list workspaces
turbo ls --filter=./packages/*  # list filtered workspaces
TURBO_LOG_VERBOSITY=debug turbo run build  # debug cache misses