turborepo

name turborepo description Turborepo monorepo build system guidance. Triggers on: turbo.json, task pipelines, dependsOn, caching, remote cache, the "turbo" CLI, --filter, --affected, CI optimization, environment variables, internal packages, monorepo structure/best practices, and boundaries. Use when user: configures tasks/workflows/pipelines, creates packages, sets up monorepo, shares code between apps, runs changed/affected packages, debugs cache, or has apps/packages directories. metadata {"version":"2.9.19-canary.9"} Turborepo Skill Build system for JavaScript/TypeScript monorepos. Turborepo caches task outputs and runs tasks in parallel based on dependency graph. IMPORTANT: Package Tasks, Not Root Tasks Prefer package tasks over Root Tasks. When creating tasks/scripts/pipelines, you MUST default to package tasks: Add the script to each relevant package's package.json Register the task in root turbo.json Root package.json only delegates via turbo run <task> DO NOT put task logic in root package.json when it can live in packages. This defeats Turborepo's parallelization. // DO THIS: Scripts in each package // apps/web/package.json { "scripts" : { "build" : "next build" , "lint" : "eslint ." , "test" : "vitest" } } // apps/api/package.json { "scripts" : { "build" : "tsc" , "lint" : "eslint ." , "test" : "vitest" } } // packages/ui/package.json { "scripts" : { "build" : "tsc" , "lint" : "eslint ." , "test" : "vitest" } } // turbo.json - register tasks { "tasks" : { "build" : { "dependsOn" : [ "^build" ] , "outputs" : [ "dist/**" ] } , "lint" : { } , "test" : { "dependsOn" : [ "build" ] } } } // Root package.json - ONLY delegates, no task logic { "scripts" : { "build" : "turbo run build" , "lint" : "turbo run lint" , "test" : "turbo run test" } } // DO NOT DO THIS - defeats parallelization // Root package.json { "scripts" : { "build" : "cd apps/web && next build && cd ../api && tsc" , "lint" : "eslint apps/ packages/" , "test" : "vitest" } } Root Tasks ( //#taskname ) are ONLY for tasks that truly cannot exist in packages, such as Vitest Projects' //#test , repo-wide release scripts, or tooling that does not invoke turbo itself. Secondary Rule: turbo run vs turbo Always use turbo run when the command is written into code: // package.json - ALWAYS "turbo run" { "scripts" : { "build" : "turbo run build" } } # CI workflows - ALWAYS "turbo run" - run: turbo run build --affected The shorthand turbo <tasks> is ONLY for one-off terminal commands typed directly by humans or agents. Never write turbo build into package.json, CI, or scripts. Quick Decision Trees "I need to configure a task" Configure a task? ├─ Define task dependencies → references/configuration/tasks.md ├─ Lint/check-types (parallel + caching) → Use Transit Nodes pattern (see below) ├─ Specify build outputs → references/configuration/tasks.md#outputs ├─ Handle environment variables → references/environment/RULE.md ├─ Set up dev/watch tasks → references/configuration/tasks.md#persistent ├─ Package-specific config → references/configuration/RULE.md#package-configurations └─ Global settings (cacheDir, daemon) → references/configuration/global-options.md "My cache isn't working" Cache problems? ├─ Tasks run but outputs not restored → Missing `outputs` key ├─ Cache misses unexpectedly → references/caching/gotchas.md ├─ Need to debug hash inputs → Use --summarize or --dry ├─ Want to skip cache entirely → Use --force or cache: false ├─ Remote cache not working → references/caching/remote-cache.md └─ Environment causing misses → references/environment/gotchas.md "I want to run only changed packages" Run only what changed? ├─ Changed packages + dependents (RECOMMENDED) → turbo run build --affected ├─ Custom base branch → --affected --affected-base=origin/develop ├─ Manual git comparison → --filter=...[origin/main] └─ See all filter options → references/filtering/RULE.md --affected is the primary way to run only changed packages. It automatically compares against the default branch and includes dependents. "I want to filter packages" Filter packages? ├─ Only changed packages → --affected (see above) ├─ By package name → --filter=web ├─ By directory → --filter=./apps/* ├─ Package + dependencies → --filter=web... ├─ Package + dependents → --filter=...web └─ Complex combinations → references/filtering/patterns.md "Environment variables aren't working" Environment issues? ├─ Vars not available at runtime → Strict mode filtering (default) ├─ Cache hits with wrong env → Var not in `env` key ├─ .env changes not causing rebuilds → .env not in `inputs` ├─ CI variables missing → references/environment/gotchas.md └─ Framework vars (NEXT_PUBLIC_*) → Auto-included via inference "I need to set up CI" CI setup? ├─ GitHub Actions → references/ci/github-actions.md ├─ Vercel deployment → references/ci/vercel.md ├─ Remote cache in CI → references/caching/remote-cache.md ├─ Only build changed packages → --affected flag ├─ Skip unnecessary builds → turbo-ignore (references/cli/commands.md) └─ Skip container setup when no changes → turbo-ignore "I want to watch for changes during development" Watch mode? ├─ Re-run tasks on change → turbo watch (references/watch/RULE.md) ├─ Dev servers with dependencies → Use `with` key (references/configuration/tasks.md#with) ├─ Restart dev server on dep change → Use `interruptible: true` └─ Persistent dev tasks → Use `persistent: true` "I need to create/structure a package" Package creation/structure? ├─ Create an internal package → references/best-practices/packages.md ├─ Repository structure → references/best-practices/structure.md ├─ Dependency management → references/best-practices/dependencies.md ├─ Best practices overview → references/best-practices/RULE.md ├─ JIT vs Compiled packages → references/best-practices/packages.md#compilation-strategies └─ Sharing code between apps → references/best-practices/RULE.md#package-types "How should I structure my monorepo?" Monorepo structure? ├─ Standard layout (apps/, packages/) → references/best-practices/RULE.md ├─ Package types (apps vs libraries) → references/best-practices/RULE.md#package-types ├─ Creating internal packages → references/best-practices/packages.md ├─ TypeScript configuration → references/best-practices/structure.md#typescript-configuration ├─ ESLint configuration → references/best-practices/structure.md#eslint-configuration ├─ Dependency management → references/best-practices/dependencies.md └─ Enforce package boundaries → references/boundaries/RULE.md "I want to enforce architectural boundaries" Enforce boundaries? ├─ Check for violations → turbo boundaries ├─ Tag packages → references/boundaries/RULE.md#tags ├─ Restrict which packages can import others → references/boundaries/RULE.md#rule-types └─ Prevent cross-package file imports → references/boundaries/RULE.md Critical Anti-Patterns Using turbo Shorthand in Code turbo run is recommended in package.json scripts and CI pipelines. The shorthand turbo <task> is intended for interactive terminal use. // WRONG - using shorthand in package.json { "scripts" : { "build" : "turbo build" , "dev" : "turbo dev" } } // CORRECT { "scripts" : { "build" : "turbo run build" , "dev" : "turbo run dev" } } # WRONG - using shorthand in CI - run: turbo build --affected # CORRECT - run: turbo run build --affected Root Scripts Bypassing Turbo Root package.json scripts MUST delegate to turbo run , not run tasks directly. // WRONG - bypasses turbo entirely { "scripts" : { "build" : "bun build" , "dev" : "bun dev" } } // CORRECT - delegates to turbo { "scripts" : { "build" : "turbo run build" , "dev" : "turbo run dev" } } Using && to Chain Turbo Tasks Don't chain turbo tasks with && . Let turbo orchestrate. // WRONG - turbo task not using turbo run { "scripts" : { "changeset:publish" : "bun build && changeset publish" } } // CORRECT { "scripts" : { "changeset:publish" : "turbo run build && changeset publish" } } prebuild Scripts That Manually Build Dependencies Scripts like prebuild that manually build other packages bypass Turborepo's dependency graph. // WRONG - manually building dependencies { "scripts" : { "prebuild" : "cd ../../packages/types && bun run build && cd ../utils && bun run build" , "build" : "next build" } } However, the fix depends on whether workspace dependencies are declared: If dependencies ARE declared (e.g., "@repo/types": "workspace:*" in package.json), remove the prebuild script. Turbo's dependsOn: ["^build"] handles this automatically. If dependencies are NOT declared , the prebuild exists because ^build won't trigger without a dependency relationship. The fix is to: Add the dependency to package.json: "@repo/types": "workspace:*" Then remove the prebuild script // CORRECT - declare dependency, let turbo handle build order // package.json { "dependencies" : { "@repo/types" : "workspace:*" , "@repo/utils" : "workspace:*" } , "scripts" : { "build" : "next build" } } // turbo.json { "tasks" : { "build" : { "dependsOn" : [ "^build" ] } } } Key insight: ^build only runs build in packages listed as dependencies. No dependency declaration = no automatic build ordering. Overly Broad globalDependencies globalDependencies affects ALL tasks in ALL packages via the global hash — tasks cannot opt out of specific files, even with negation globs in inputs . Be specific. // WRONG - heavy hammer, affects all hashes { "globalDependencies" : [ "**/.env.*local" ] } // BETTER - move to task-level inputs { "globalDependencies" : [ ".env" ] , "tasks" : { "build" : { "inputs" : [ "$TURBO_DEFAULT$" , ".env*" ] , "outputs" : [ "dist/**" ] } } } With futureFlags.globalConfiguration , this problem is reduced because global.inputs files are folded into each task's inputs (not the global hash). Tasks can exclude specific files: // BEST - global.inputs with per-task exclusion { "futureFlags" : { "globalConfiguration" : true } , "global" : { "inputs" : [ ".env" ] } , "tasks" : { "build" : { "outputs" : [ "dist/**" ] } , "lint" : { "inputs" : [ "$TURBO_DEFAULT$" , "!$TURBO_ROOT$/.env" ] } } } Repetitive Task Configuration Look for repeated configuration across tasks that can be collapsed. Turborepo supports shared configuration patterns. // WRONG - repetitive env and inputs across tasks { "tasks" : { "build" : { "env" : [ "API_URL" , "DATABASE_URL" ] , "inputs" : [ "$TURBO_DEFAULT$" , ".env*" ] } , "test" : { "env" : [ "API_URL" , "DATABASE_URL" ] , "inputs" : [ "$TURBO_DEFAULT$" , ".env*" ] } , "dev" : { "env" : [ "API_URL" , "DATABASE_URL" ] , "inputs" : [ "$TURBO_DEFAULT$" , ".env*" ] , "cache" : false , "persistent" : true } } } // BETTER - use globalEnv and globalDependencies for shared config { "globalEnv" : [ "API_URL" , "DATABASE_URL" ] , "globalDependencies" : [ ".env*" ] , "tasks" : { "build" : { } , "test" : { } , "dev" : { "cache" : false , "persistent" : true } } } When to use global vs task-level: globalEnv / globalDependencies - affects ALL tasks, use for truly shared config Task-level env / inputs - use when only specific tasks need it NOT an Anti-Pattern: Large env Arrays A large env array (even 50+ variables) is not a problem. It usually means the user was thorough about declaring their build's environment dependencies. Do not flag this as an issue.