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

Pattern	Syntax	Key Points
Schema	`"$schema": "https://turborepo.dev/schema.json"`	Always include in turbo.json
Dependency build	`"dependsOn": ["^build"]`	Build dependencies first
Same-package task	`"dependsOn": ["codegen"]`	Run in same package first
Specific package	`"dependsOn": ["pkg#task"]`	Named package's task
Parallel lint/typecheck	Transit Nodes pattern	Cache invalidation without sequential execution
Dev server	`"persistent": true, "cache": false`	Long-running, non-cacheable
Sidecar tasks	`"with": ["api#dev"]`	Run tasks concurrently alongside
Watch mode	`turbo watch dev`	Re-run on file changes
Filter by package	`--filter=web`	Single package
Filter with deps	`--filter=web...`	Package + dependencies
Changed packages	`--affected`	Changed + dependents
Debug cache	`--summarize` or `--dry`	See hash inputs
Package config	`turbo.json` with `"extends": ["//"]`	Per-package overrides
Composable config	`"extends": ["@repo/config"]`	Extend from any workspace package
Extend arrays	`"$TURBO_EXTENDS$"` in arrays	Append to inherited config instead of replacing
Env vars in hash	`"env": ["API_URL"]`	Cache invalidation on change
Boundaries	`turbo boundaries`	Enforce package isolation and import rules
Query graph	`turbo query`	GraphQL interface to package/task graphs
Code generation	`turbo generate`	Scaffold new packages and components
List packages	`turbo ls`	List all packages in monorepo
Devtools	`turbo devtools`	Visual Package Graph and Task Graph explorer
Docker pruned workspace	`turbo prune <pkg> --docker`	Minimal monorepo slice for container builds

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

Mistake	Correct Pattern
Putting build logic in root `package.json` scripts instead of per-package	Define scripts in each package and use `turbo run` in root to delegate
Using `^build` without declaring `workspace:*` dependency	Add the dependency in `package.json` first; `^build` only triggers for declared dependencies
Chaining turbo tasks with `&&` in package scripts	Use `dependsOn` in `turbo.json` to declare task ordering
Not adding environment variables to the `env` key in turbo.json	Declare all build-affecting env vars in `env` so cache hashes correctly
Using `--parallel` flag to bypass dependency ordering	Configure `dependsOn` correctly or use transit nodes for parallel tasks with proper cache invalidation
Using outdated schema URL	Use `https://turborepo.dev/schema.json` in `$schema` field
Overriding inherited arrays in package configs	Use $TURBO_EXTENDS$ in arrays to append instead of replace
Defining tasks in root `turbo.json` that belong to a specific package	Define tasks inside the package's own `turbo.json` with `extends: ["//"]`
Using `turbo <task>` shorthand in scripts or CI	Use `turbo run <task>` in `package.json` scripts and CI pipelines; shorthand is for interactive use only

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.

turborepo