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.
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
1---
2name: turborepo
3description: |
4 Turborepo monorepo build system and orchestration. Covers task pipelines, dependsOn syntax, caching configuration, remote cache, filtering, CI optimization, environment variables, workspace management, watch mode, package boundaries, and code generation.
5
6 Use when configuring tasks, creating packages, setting up monorepo, sharing code between apps, running changed packages, debugging cache, optimizing CI, resolving workspace dependencies, enforcing package boundaries, or generating code.
7license: MIT
8metadata:
9 author: oakoss
10 version: '1.2'
11user-invocable: false
12---
13
14# Turborepo
15
16## Overview
17
18Build 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).
19
20**When to use:** Monorepo task orchestration, build caching, CI optimization, workspace dependency management, package boundary enforcement.
21
22**When NOT to use:** Single-package projects, non-JavaScript monorepos, projects without build steps.
23
24## Quick Reference
25
26| Pattern | Syntax | Key Points |
27| ----------------------- | ------------------------------------------------ | ----------------------------------------------- |
28| Schema | `"$schema": "https://turborepo.dev/schema.json"` | Always include in turbo.json |
29| Dependency build | `"dependsOn": ["^build"]` | Build dependencies first |
30| Same-package task | `"dependsOn": ["codegen"]` | Run in same package first |
31| Specific package | `"dependsOn": ["pkg#task"]` | Named package's task |
32| Parallel lint/typecheck | Transit Nodes pattern | Cache invalidation without sequential execution |
33| Dev server | `"persistent": true, "cache": false` | Long-running, non-cacheable |
34| Sidecar tasks | `"with": ["api#dev"]` | Run tasks concurrently alongside |
35| Watch mode | `turbo watch dev` | Re-run on file changes |
36| Filter by package | `--filter=web` | Single package |
37| Filter with deps | `--filter=web...` | Package + dependencies |
38| Changed packages | `--affected` | Changed + dependents |
39| Debug cache | `--summarize` or `--dry` | See hash inputs |
40| Package config | `turbo.json` with `"extends": ["//"]` | Per-package overrides |
41| Composable config | `"extends": ["@repo/config"]` | Extend from any workspace package |
42| Extend arrays | `"$TURBO_EXTENDS$"` in arrays | Append to inherited config instead of replacing |
43| Env vars in hash | `"env": ["API_URL"]` | Cache invalidation on change |
44| Boundaries | `turbo boundaries` | Enforce package isolation and import rules |
45| Query graph | `turbo query` | GraphQL interface to package/task graphs |
46| Code generation | `turbo generate` | Scaffold new packages and components |
47| List packages | `turbo ls` | List all packages in monorepo |
48| Devtools | `turbo devtools` | Visual Package Graph and Task Graph explorer |
49| Docker pruned workspace | `turbo prune <pkg> --docker` | Minimal monorepo slice for container builds |
50
51## Decision Trees
52
53### Configure a Task
54
55```text
56Configure a task?
57+-- Define task dependencies -> dependsOn in turbo.json
58+-- Lint/check-types (parallel) -> Transit Nodes pattern
59+-- Specify build outputs -> outputs key
60+-- Handle environment variables -> env key or globalEnv
61+-- Dev/watch tasks -> persistent: true, cache: false
62+-- Sidecar tasks (run alongside) -> with key
63+-- Package-specific config -> Package turbo.json with extends: ["//"]
64+-- Composable config -> extends from any workspace package
65+-- Global settings -> globalEnv, globalDependencies, cacheDir
66```
67
68### Cache Problems
69
70```text
71Cache problems?
72+-- Outputs not restored -> Missing outputs key
73+-- Unexpected cache misses -> Use --summarize or --dry to debug
74+-- Skip cache entirely -> --force or cache: false
75+-- Remote cache not working -> Check turbo login/link
76+-- Environment causing misses -> Var not in env key
77```
78
79### Filter Packages
80
81```text
82Filter packages?
83+-- By package name -> --filter=web
84+-- By directory -> --filter=./apps/*
85+-- Package + dependencies -> --filter=web...
86+-- Package + dependents -> --filter=...web
87+-- Changed + dependents -> --affected
88```
89
90### Explore Repository
91
92```text
93Explore repository?
94+-- List all packages -> turbo ls
95+-- Query dependency graph -> turbo query
96+-- Visualize graphs -> turbo devtools
97+-- Check boundary violations -> turbo boundaries
98+-- Generate new package -> turbo generate workspace
99+-- Run custom generator -> turbo generate run [name]
100```
101
102## Common Mistakes
103
104| Mistake | Correct Pattern |
105| ------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
106| 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 |
107| Using `^build` without declaring `workspace:*` dependency | Add the dependency in `package.json` first; `^build` only triggers for declared dependencies |
108| Chaining turbo tasks with `&&` in package scripts | Use `dependsOn` in `turbo.json` to declare task ordering |
109| Not adding environment variables to the `env` key in turbo.json | Declare all build-affecting env vars in `env` so cache hashes correctly |
110| Using `--parallel` flag to bypass dependency ordering | Configure `dependsOn` correctly or use transit nodes for parallel tasks with proper cache invalidation |
111| Using outdated schema URL | Use `https://turborepo.dev/schema.json` in `$schema` field |
112| Overriding inherited arrays in package configs | Use `$TURBO_EXTENDS$` in arrays to append instead of replace |
113| Defining tasks in root `turbo.json` that belong to a specific package | Define tasks inside the package's own `turbo.json` with `extends: ["//"]` |
114| 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 |
115
116## Delegation
117
118- **Monorepo structure exploration**: Use `Explore` agent to discover packages, workspace layout, and dependency relationships
119- **Pipeline configuration and optimization**: Use `Task` agent to set up turbo.json tasks, configure caching, and debug cache misses
120- **Monorepo architecture planning**: Use `Plan` agent to design package boundaries, shared libraries, and CI optimization strategy
121
122> If the `pnpm-workspace` skill is available, delegate workspace setup, dependency linking, catalogs, and `pnpm deploy` to it.
123> If the `changesets` skill is available, delegate versioning, changelog generation, and npm publishing to it.
124
125## References
126
127- [Task configuration and dependsOn patterns](references/task-configuration.md)
128- [Caching, outputs, and debugging cache issues](references/caching.md)
129- [Filtering, affected packages, and CI patterns](references/filtering-and-ci.md)
130- [Workspace structure and package management](references/workspace-structure.md)
131- [Environment variables and modes](references/environment-variables.md)
132- [Watch mode, dev tasks, and anti-patterns](references/dev-and-anti-patterns.md)
133- [Boundaries, query, and code generation](references/boundaries-and-tooling.md)
oakoss