Turborepo

Turborepo

Overview

Build system for JavaScript/TypeScript monorepos. Caches task outputs and runs tasks in parallel based on dependency graph. Always create package tasks (not root tasks), use turbo run in scripts, and let dependsOn manage execution order. Configuration uses turbo.json (or turbo.jsonc for comments).

When to use: Monorepo task orchestration, build caching, CI optimization, workspace dependency management, package boundary enforcement.

When NOT to use: Single-package projects, non-JavaScript monorepos, projects without build steps.

Quick Reference

Decision Trees

Configure a Task

Configure a task?
+-- Define task dependencies       -> dependsOn in turbo.json
+-- Lint/check-types (parallel)    -> Transit Nodes pattern
+-- Specify build outputs          -> outputs key
+-- Handle environment variables   -> env key or globalEnv
+-- Dev/watch tasks                -> persistent: true, cache: false
+-- Sidecar tasks (run alongside)  -> with key
+-- Package-specific config        -> Package turbo.json with extends: ["//"]
+-- Composable config              -> extends from any workspace package
+-- Global settings                -> globalEnv, globalDependencies, cacheDir

Cache Problems

Cache problems?
+-- Outputs not restored           -> Missing outputs key
+-- Unexpected cache misses        -> Use --summarize or --dry to debug
+-- Skip cache entirely            -> --force or cache: false
+-- Remote cache not working       -> Check turbo login/link
+-- Environment causing misses     -> Var not in env key

Filter Packages

Filter packages?
+-- By package name                -> --filter=web
+-- By directory                   -> --filter=./apps/*
+-- Package + dependencies         -> --filter=web...
+-- Package + dependents           -> --filter=...web
+-- Changed + dependents           -> --affected

Explore Repository

Explore repository?
+-- List all packages              -> turbo ls
+-- Query dependency graph         -> turbo query
+-- Visualize graphs               -> turbo devtools
+-- Check boundary violations      -> turbo boundaries
+-- Generate new package           -> turbo generate workspace
+-- Run custom generator           -> turbo generate run [name]

Common Mistakes

Delegation

• Monorepo structure exploration: Use Explore agent to discover packages, workspace layout, and dependency relationships
• Pipeline configuration and optimization: Use Task agent to set up turbo.json tasks, configure caching, and debug cache misses
• Monorepo architecture planning: Use Plan agent to design package boundaries, shared libraries, and CI optimization strategy

If the pnpm-workspace skill is available, delegate workspace setup, dependency linking, catalogs, and pnpm deploy to it.

If the changesets skill is available, delegate versioning, changelog generation, and npm publishing to it.

References

• Task configuration and dependsOn patterns
• Caching, outputs, and debugging cache issues
• Filtering, affected packages, and CI patterns
• Workspace structure and package management
• Environment variables and modes
• Watch mode, dev tasks, and anti-patterns
• Boundaries, query, and code generation

Boundaries, Query, and Code Generation

Boundaries

Enforce package isolation rules to catch import violations and undeclared dependencies.

Enable Boundaries

Add to root turbo.json:

{
  "boundaries": {}
}

Run the check:

turbo boundaries

Catches two types of violations:

• Importing a file outside the package's directory
• Importing a package not declared in the package's package.json

Boundary Tags

Tags allow custom rules for package dependency relationships. Define tags in each package's turbo.json:

{
  "tags": ["internal"],
  "extends": ["//"],
  "tasks": {}
}

Define tag rules in root turbo.json:

{
  "boundaries": {
    "tags": {
      "public": {
        "dependencies": {
          "allow": ["public"]
        }
      },
      "internal": {
        "dependents": {
          "deny": ["public"]
        }
      }
    }
  }
}

Tag Rule Options

Rules apply transitively -- violations are caught even through intermediate dependencies.

Common Boundary Patterns

Separate public and internal packages:

{
  "boundaries": {
    "tags": {
      "public": {
        "dependencies": {
          "deny": ["internal"]
        }
      }
    }
  }
}

Isolate feature domains:

{
  "boundaries": {
    "tags": {
      "auth": {
        "dependencies": {
          "allow": ["auth", "shared"]
        }
      },
      "billing": {
        "dependencies": {
          "allow": ["billing", "shared"]
        }
      }
    }
  }
}

turbo query

Run GraphQL queries against the repository's package and task graphs:

turbo query

Opens a GraphiQL playground when run without arguments.

Query Examples

Find all packages that depend on a specific package:

turbo query "{ packages(filter: { dependents: { name: { equal: \"@repo/ui\" } } }) { items { name } } }"

Query from a file:

turbo query path/to/query.gql

Machine-readable output:

turbo query --output=json "{ packages { items { name path } } }"

Use Cases

• Discover dependency relationships between packages
• Find changed packages and their dependents
• Audit task configurations across the monorepo
• Build custom CI pipelines based on graph data

turbo generate

Scaffold new packages and run custom generators.

Create a New Package

turbo generate workspace
turbo generate workspace --name @repo/new-lib --copy @repo/ui

Options:

Custom Generators

Define generators in turbo/generators/config.ts:

import type { PlopTypes } from '@turbo/gen';

export default function generator(plop: PlopTypes.NodePlopAPI): void {
  plop.setGenerator('component', {
    description: 'Create a new React component',
    prompts: [
      {
        type: 'input',
        name: 'name',
        message: 'Component name?',
      },
    ],
    actions: [
      {
        type: 'add',
        path: 'packages/ui/src/{{kebabCase name}}.tsx',
        templateFile: 'turbo/generators/templates/component.hbs',
      },
    ],
  });
}

Run a custom generator:

turbo generate run component
turbo gen component --args "Button"

Install the generator dependency:

pnpm add -D @turbo/gen

turbo ls

List all packages in the monorepo:

turbo ls

Shows package names and their directories.

Filter Package List

turbo ls --filter=./packages/*
turbo ls --affected

turbo devtools

Visual explorer for Package Graph and Task Graph:

turbo devtools

Hot-reloads as you make changes to turbo.json or package structure. Useful for debugging dependency relationships and task ordering.

Caching and Debugging

Diagnostic Tools

--summarize

Generates a JSON file with all hash inputs. Compare two runs to find differences.

turbo build --summarize
# Creates .turbo/runs/<run-id>.json

# Compare runs
diff .turbo/runs/<first-run>.json .turbo/runs/<second-run>.json

--dry / --dry=json

See what would run without executing:

turbo build --dry
turbo build --dry=json  # machine-readable output

--force

Skip reading cache, re-execute all tasks:

turbo build --force

Unexpected Cache Misses

Symptom: Task runs when you expected a cache hit.

Checklist:

1. Run with --summarize, compare with previous run 2. Check env vars with --dry=json 3. Look for lockfile/config changes in git 4. Check if environment variables are in env key 5. Check if .env files are in inputs 6. Verify outputs includes all produced files

Common Causes

• Environment variable changed: Different API_URL between runs
• .env file changed: Not tracked by default, add to inputs
• Lockfile changed: Installing/updating packages changes global hash
• turbo.json changed: Config changes invalidate global hash

Incorrect Cache Hits

Symptom: Cached output is stale/wrong.

• Missing env var: Task uses a var not listed in env
• Missing file in inputs: Task reads a file outside default inputs

{
  "tasks": {
    "build": {
      "env": ["API_URL"],
      "inputs": ["$TURBO_DEFAULT$", ".env", ".env.*"]
    }
  }
}

Remote Caching

Configure remote cache (Vercel or custom S3-based) for fast CI:

• Use persistent: true and cache: false for dev servers to prevent cache poisoning
• Use --summarize or --dry to debug cache behavior

GitHub Actions Setup

jobs:
  build:
    runs-on: ubuntu-latest
    env:
      TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
      TURBO_TEAM: ${{ vars.TURBO_TEAM }}

Alternative: actions/cache

If you can't use remote cache:

- uses: actions/cache@v5
  with:
    path: .turbo
    key: turbo-${{ runner.os }}-${{ hashFiles('**/turbo.json', '**/package-lock.json') }}
    restore-keys: |
      turbo-${{ runner.os }}-

Useful Flags

# Only show output for cache misses
turbo build --output-logs=new-only

# Show output for everything
turbo build --output-logs=full

# See why tasks are running
turbo build --verbosity=2

Watch Mode and Anti-Patterns

Watch Mode

Re-run tasks on file changes:

turbo watch dev

Dev Task Configuration

{
  "tasks": {
    "dev": {
      "dependsOn": ["^dev"],
      "cache": false,
      "persistent": false
    }
  }
}

Apps override with persistent:

{
  "extends": ["//"],
  "tasks": {
    "dev": { "persistent": true }
  }
}

with Key for Runtime Dependencies

Run tasks alongside (concurrent, not sequential):

{
  "tasks": {
    "dev": {
      "with": ["api#dev"],
      "persistent": true,
      "cache": false
    }
  }
}

interruptible Tasks

Allow turbo watch to restart tasks on dependency changes:

{
  "tasks": {
    "dev": {
      "persistent": true,
      "interruptible": true,
      "cache": false
    }
  }
}

Troubleshooting

Tasks Running Sequentially

1. Check dependsOn -- ^build forces sequential execution 2. For lint/typecheck, use Transit Nodes pattern instead 3. Remove unnecessary dependsOn entries

Build Order Wrong

1. Verify workspace:* dependency is declared in package.json 2. Confirm dependsOn: ["^build"] is set in turbo.json 3. ^build only triggers for declared dependencies

Dev Server Not Picking Up Changes

1. Use turbo watch dev instead of turbo run dev 2. Set interruptible: true on dev tasks that should restart 3. Ensure dependency packages have a dev script

Environment Variables Missing

1. Check if strict mode is filtering them (default behavior) 2. Add to env, globalEnv, or globalPassThroughEnv 3. Framework-specific vars are auto-included via inference

Monorepo Structure Validation

• Use turbo boundaries to enforce package isolation
• Run turbo run build --dry to verify task graph
• Run turbo query to explore package and task graphs via GraphQL
• Run turbo ls to list all packages in the monorepo
• Use --filter to test specific packages in isolation

Anti-Patterns

Using --parallel Flag

Bypasses dependency graph. Configure dependsOn correctly or use transit nodes instead.

../ in inputs

// Bad
{ "inputs": ["$TURBO_DEFAULT$", "../shared-config.json"] }

// Good
{ "inputs": ["$TURBO_DEFAULT$", "$TURBO_ROOT$/shared-config.json"] }

Too Many Root Dependencies

Root package.json should only have repo tooling (turbo, prettier, etc.). App dependencies belong in each package.

Environment Variables

env Key

Variables listed in env affect cache hits -- changing the value invalidates cache.

{
  "tasks": {
    "build": {
      "env": ["API_URL", "NEXT_PUBLIC_*", "!DEBUG"]
    }
  }
}

Use wildcards (*) for framework-prefixed vars. Use ! to exclude from hash.

globalEnv

Variables that affect all tasks globally:

{
  "globalEnv": ["NODE_ENV"],
  "globalDependencies": [".env"]
}

.env Files in Inputs

Turbo does NOT load .env files (your framework does), but Turbo needs to know about changes:

{
  "tasks": {
    "build": {
      "env": ["API_URL"],
      "inputs": ["$TURBO_DEFAULT$", ".env", ".env.*"]
    }
  }
}

Strict Mode (Default)

Only explicitly configured variables are available to tasks. Unlisted vars are filtered out.

Benefits: Guarantees cache correctness, prevents accidental dependencies, reproducible builds.

turbo run build --env-mode=strict

Loose Mode

All system environment variables are available but only env/globalEnv vars affect the hash:

turbo run build --env-mode=loose

Risks: Cache may restore incorrect results if unhashed vars changed. Use for migrating legacy projects.

Framework Inference

Turborepo auto-detects frameworks and includes their conventional env vars:

Disabling Framework Inference

turbo run build --framework-inference=false

Or exclude specific patterns:

{
  "tasks": {
    "build": {
      "env": ["!NEXT_PUBLIC_*"]
    }
  }
}

passThroughEnv

Variables available at runtime but NOT included in cache hash:

{
  "tasks": {
    "build": {
      "passThroughEnv": ["AWS_SECRET_KEY", "GITHUB_TOKEN"]
    }
  }
}

Changes to these vars won't cause cache misses.

globalPassThroughEnv

For CI variables that need to be available but shouldn't affect cache:

{
  "globalPassThroughEnv": ["GITHUB_TOKEN", "CI"]
}

Anti-Patterns

Environment Variables Not Hashed

// Bad: API_URL changes won't rebuild
{ "tasks": { "build": { "outputs": ["dist/**"] } } }

// Good: API_URL in hash
{ "tasks": { "build": { "outputs": ["dist/**"], "env": ["API_URL"] } } }

Overly Broad globalDependencies

// Bad: affects all hashes
{ "globalDependencies": ["**/.env.*local"] }

// Better: task-level inputs
{
  "globalDependencies": [".env"],
  "tasks": {
    "build": { "inputs": ["$TURBO_DEFAULT$", ".env*"] }
  }
}

Root .env File

Package .env files in each app, not a single root .env. Root .env creates implicit coupling, coarse cache invalidation, and security risks.

NOT an Anti-Pattern

A large env array (50+ variables) is fine. It means thorough environment declaration.

Checking Environment Mode

turbo run build --dry=json | jq '.tasks[].environmentVariables'

Filtering and CI Patterns

Filter Syntax

Single Package

turbo run build --filter=web
turbo run test --filter=@acme/api

Package with Dependencies

Build a package and everything it depends on:

turbo run build --filter=web...

Package Dependents

Run in all packages that depend on a library:

turbo run test --filter=...ui

Dependents Only (Exclude Target)

turbo run test --filter=...^ui

Changed Packages

turbo run lint --filter=[HEAD^1]
turbo run lint --filter=[main...HEAD]

Changed + Dependents

turbo run build test --filter=...[HEAD^1]
# Or shortcut:
turbo run build test --affected

Directory-Based

turbo run build --filter=./apps/*
turbo run build --filter=./apps/web --filter=./apps/api

Scope-Based

turbo run build --filter=@acme/*

Exclusions

turbo run build --filter=./apps/* --filter=!admin
turbo run lint --filter=!legacy-app --filter=!deprecated-pkg

Custom Affected Base

turbo run build --affected --affected-base=origin/develop

Debugging Filters

turbo run build --filter=web... --dry
turbo run build --filter=...[HEAD^1] --dry=json

GitHub Actions CI

Complete Example

name: CI

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    env:
      TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
      TURBO_TEAM: ${{ vars.TURBO_TEAM }}

    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 2

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

      - uses: actions/setup-node@v6
        with:
          node-version: 20
          cache: 'pnpm'

      - name: Install dependencies
        run: pnpm install --frozen-lockfile

      - name: Build
        run: turbo run build --affected

      - name: Test
        run: turbo run test --affected

      - name: Lint
        run: turbo run lint --affected

Package Manager Setup

# pnpm
- uses: pnpm/action-setup@v3
  with:
    version: 9
- run: pnpm install --frozen-lockfile

# Yarn
- run: yarn install --frozen-lockfile

# Bun
- uses: oven-sh/setup-bun@v1
- run: bun install --frozen-lockfile

Remote Cache Setup

1. Create Vercel access token at Vercel Dashboard 2. Add TURBO_TOKEN as repository secret 3. Add TURBO_TEAM as repository variable 4. Reference in workflow env block

CI Patterns Summary

Task Configuration

Standard Build Pipeline

{
  "$schema": "https://turborepo.dev/schema.json",
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**", ".next/**", "!.next/cache/**"]
    },
    "dev": {
      "cache": false,
      "persistent": true
    }
  }
}

dependsOn Syntax

{
  "tasks": {
    "build": { "dependsOn": ["^build"] },
    "test": { "dependsOn": ["build"] },
    "deploy": { "dependsOn": ["web#build"] }
  }
}

The ^ prefix is crucial -- without it, you're referencing the same package.

Transit Nodes for Parallel Tasks

Tasks like lint and typecheck can run in parallel but need dependency-aware caching:

{
  "tasks": {
    "transit": { "dependsOn": ["^transit"] },
    "lint": { "dependsOn": ["transit"] },
    "check-types": { "dependsOn": ["transit"] }
  }
}

DO NOT use `dependsOn: ["^lint"]` -- this forces sequential execution. DO NOT use `dependsOn: []` -- this breaks cache invalidation.

The transit task creates dependency relationships without running anything (no matching script).

outputs

Glob patterns for files to cache. If omitted, nothing is cached.

{
  "tasks": {
    "build": {
      "outputs": ["dist/**", "build/**"]
    }
  }
}

Framework examples:

inputs

Files considered when calculating task hash. Defaults to all tracked files.

{
  "tasks": {
    "build": {
      "inputs": [
        "$TURBO_DEFAULT$",
        "!README.md",
        "$TURBO_ROOT$/tsconfig.base.json"
      ]
    }
  }
}

Task Options Reference

Package Configurations

Use per-package turbo.json instead of cluttering root with package#task overrides:

{
  "extends": ["//"],
  "tasks": {
    "test": { "outputs": ["coverage/**"] }
  }
}

Dev Task with ^dev Pattern (for turbo watch)

{
  "tasks": {
    "dev": {
      "dependsOn": ["^dev"],
      "cache": false,
      "persistent": false
    }
  }
}

{
  "extends": ["//"],
  "tasks": {
    "dev": { "persistent": true }
  }
}

Packages run one-shot dev scripts; apps override with persistent: true. Use with turbo watch dev.

Composable Configuration (Turborepo 2.7+)

Package configurations can extend from any workspace package, not just root:

{
  "extends": ["@repo/turbo-config"],
  "tasks": {
    "build": {
      "dependsOn": ["$TURBO_EXTENDS$", "codegen"]
    }
  }
}

$TURBO_EXTENDS$ appends to inherited arrays instead of replacing them. Without it, the local dependsOn completely overrides the inherited value.

Workspace Structure

Workspace Configuration

# pnpm-workspace.yaml
packages:
  - 'apps/*'
  - 'packages/*'

Root package.json

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

Key points:

• private: true prevents accidental publishing
• Scripts only delegate to turbo run -- no actual build logic
• Minimal devDependencies (just turbo and repo tools)
• App dependencies belong in each package, not root

Package Tasks, Not Root Tasks

// apps/web/package.json
{ "scripts": { "build": "next build", "lint": "eslint .", "test": "vitest" } }

// packages/ui/package.json
{ "scripts": { "build": "tsc", "lint": "eslint .", "test": "vitest" } }

// Root package.json ONLY delegates
{
  "scripts": {
    "build": "turbo run build",
    "lint": "turbo run lint",
    "test": "turbo run test"
  }
}

Root Tasks (//#taskname) are only for tasks that truly cannot exist in packages.

Workspace Dependencies

Use workspace:* for internal dependencies:

{
  "dependencies": {
    "@repo/ui": "workspace:*",
    "@repo/utils": "workspace:*"
  }
}

Shared UI Package

{
  "name": "@repo/ui",
  "version": "0.0.0",
  "private": true,
  "exports": {
    ".": "./src/index.ts",
    "./styles.css": "./src/styles.css"
  },
  "peerDependencies": {
    "react": "^19.0.0"
  }
}

Shared TypeScript Config

// packages/typescript-config/base.json
{
  "compilerOptions": {
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "moduleResolution": "bundler",
    "module": "ESNext",
    "target": "ES2022"
  }
}

// packages/ui/tsconfig.json
{
  "extends": "@repo/typescript-config/library.json",
  "compilerOptions": {
    "outDir": "dist",
    "rootDir": "src"
  },
  "include": ["src"]
}

Shared ESLint Config

// packages/eslint-config/package.json
{
  "name": "@repo/eslint-config",
  "exports": {
    "./base": "./base.js",
    "./next": "./next.js",
    "./library": "./library.js"
  }
}

Anti-Patterns

Relative Imports Across Packages

// Bad
import { Button } from '../../packages/ui/src/button';

// Good
import { Button } from '@repo/ui/button';

Shared Code Inside Apps

Extract shared code to packages/, not apps/web/shared/.

prebuild Scripts

// Bad - bypasses dependency graph
{
  "scripts": {
    "prebuild": "cd ../../packages/types && bun run build",
    "build": "next build"
  }
}

// Good - declare dependency, let turbo handle order
{
  "dependencies": { "@repo/types": "workspace:*" },
  "scripts": { "build": "next build" }
}

Chaining Turbo Tasks with &&

// Bad
{ "scripts": { "changeset:publish": "bun build && changeset publish" } }

// Good
{ "scripts": { "changeset:publish": "turbo run build && changeset publish" } }

Root Scripts Bypassing Turbo

// Bad
{ "scripts": { "build": "bun build" } }

// Good
{ "scripts": { "build": "turbo run build" } }

turbo run vs turbo

Always use turbo run in code (package.json, CI, scripts). The shorthand turbo <task> is only for one-off terminal commands.

JSONC Support

Use turbo.jsonc instead of turbo.json to add comments to configuration:

{
  "$schema": "https://turborepo.dev/schema.json",
  // Build all dependencies first
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**"],
    },
  },
}

Lockfile

A lockfile is required for reproducible builds, dependency understanding, and cache correctness.