1---
2name: turborepo
3description: |
4  Turborepo monorepo build system guidance. Triggers on: turbo.json, task pipelines,
5  dependsOn, caching, remote cache, the "turbo" CLI, --filter, --affected, CI optimization, environment
6  variables, internal packages, monorepo structure/best practices, and boundaries.
7 
8  Use when user: configures tasks/workflows/pipelines, creates packages, sets up
9  monorepo, shares code between apps, runs changed/affected packages, debugs cache,
10  or has apps/packages directories.
11metadata:
12  version: 2.10.3-canary.4
13---
14 
15# Turborepo Skill
16 
17Build system for JavaScript/TypeScript monorepos. Turborepo caches task outputs and runs tasks in parallel based on dependency graph.
18 
19## IMPORTANT: Package Tasks, Not Root Tasks
20 
21**Prefer package tasks over Root Tasks.**
22 
23When creating tasks/scripts/pipelines, you MUST default to package tasks:
24 
251. Add the script to each relevant package's `package.json`
262. Register the task in root `turbo.json`
273. Root `package.json` only delegates via `turbo run <task>`
28 
29**DO NOT** put task logic in root `package.json` when it can live in packages. This defeats Turborepo's parallelization.
30 
31```json
32// DO THIS: Scripts in each package
33// apps/web/package.json
34{ "scripts": { "build": "next build", "lint": "eslint .", "test": "vitest" } }
35 
36// apps/api/package.json
37{ "scripts": { "build": "tsc", "lint": "eslint .", "test": "vitest" } }
38 
39// packages/ui/package.json
40{ "scripts": { "build": "tsc", "lint": "eslint .", "test": "vitest" } }
41```
42 
43```json
44// turbo.json - register tasks
45{
46  "tasks": {
47    "build": { "dependsOn": ["^build"], "outputs": ["dist/**"] },
48    "lint": {},
49    "test": { "dependsOn": ["build"] }
50  }
51}
52```
53 
54```json
55// Root package.json - ONLY delegates, no task logic
56{
57  "scripts": {
58    "build": "turbo run build",
59    "lint": "turbo run lint",
60    "test": "turbo run test"
61  }
62}
63```
64 
65```json
66// DO NOT DO THIS - defeats parallelization
67// Root package.json
68{
69  "scripts": {
70    "build": "cd apps/web && next build && cd ../api && tsc",
71    "lint": "eslint apps/ packages/",
72    "test": "vitest"
73  }
74}
75```
76 
77Root 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.
78 
79## Secondary Rule: `turbo run` vs `turbo`
80 
81**Always use `turbo run` when the command is written into code:**
82 
83```json
84// package.json - ALWAYS "turbo run"
85{
86  "scripts": {
87    "build": "turbo run build"
88  }
89}
90```
91 
92```yaml
93# CI workflows - ALWAYS "turbo run"
94- run: turbo run build --affected
95```
96 
97**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.
98 
99## Quick Decision Trees
100 
101### "I need to configure a task"
102 
103```
104Configure a task?
105├─ Define task dependencies → references/configuration/tasks.md
106├─ Lint/check-types (parallel + caching) → Use Transit Nodes pattern (see below)
107├─ Specify build outputs → references/configuration/tasks.md#outputs
108├─ Handle environment variables → references/environment/RULE.md
109├─ Set up dev/watch tasks → references/configuration/tasks.md#persistent
110├─ Package-specific config → references/configuration/RULE.md#package-configurations
111└─ Global settings (cacheDir, daemon) → references/configuration/global-options.md
112```
113 
114### "My cache isn't working"
115 
116```
117Cache problems?
118├─ Tasks run but outputs not restored → Missing `outputs` key
119├─ Cache misses unexpectedly → references/caching/gotchas.md
120├─ Need to debug hash inputs → Use --summarize or --dry
121├─ Want to skip cache entirely → Use --force or cache: false
122├─ Remote cache not working → references/caching/remote-cache.md
123└─ Environment causing misses → references/environment/gotchas.md
124```
125 
126### "I want to run only changed packages"
127 
128```
129Run only what changed?
130├─ Changed packages + dependents (RECOMMENDED) → turbo run build --affected
131├─ Custom base branch → --affected --affected-base=origin/develop
132├─ Manual git comparison → --filter=...[origin/main]
133└─ See all filter options → references/filtering/RULE.md
134```
135 
136**`--affected` is the primary way to run only changed packages.** It automatically compares against the default branch and includes dependents.
137 
138### "I want to filter packages"
139 
140```
141Filter packages?
142├─ Only changed packages → --affected (see above)
143├─ By package name → --filter=web
144├─ By directory → --filter=./apps/*
145├─ Package + dependencies → --filter=web...
146├─ Package + dependents → --filter=...web
147└─ Complex combinations → references/filtering/patterns.md
148```
149 
150### "Environment variables aren't working"
151 
152```
153Environment issues?
154├─ Vars not available at runtime → Strict mode filtering (default)
155├─ Cache hits with wrong env → Var not in `env` key
156├─ .env changes not causing rebuilds → .env not in `inputs`
157├─ CI variables missing → references/environment/gotchas.md
158└─ Framework vars (NEXT_PUBLIC_*) → Auto-included via inference
159```
160 
161### "I need to set up CI"
162 
163```
164CI setup?
165├─ GitHub Actions → references/ci/github-actions.md
166├─ Vercel deployment → references/ci/vercel.md
167├─ Remote cache in CI → references/caching/remote-cache.md
168├─ Only build changed packages → --affected flag
169├─ Skip unnecessary builds → turbo-ignore (references/cli/commands.md)
170└─ Skip container setup when no changes → turbo-ignore
171```
172 
173### "I want to watch for changes during development"
174 
175```
176Watch mode?
177├─ Re-run tasks on change → turbo watch (references/watch/RULE.md)
178├─ Dev servers with dependencies → Use `with` key (references/configuration/tasks.md#with)
179├─ Restart dev server on dep change → Use `interruptible: true`
180└─ Persistent dev tasks → Use `persistent: true`
181```
182 
183### "I need to create/structure a package"
184 
185```
186Package creation/structure?
187├─ Create an internal package → references/best-practices/packages.md
188├─ Repository structure → references/best-practices/structure.md
189├─ Dependency management → references/best-practices/dependencies.md
190├─ Best practices overview → references/best-practices/RULE.md
191├─ JIT vs Compiled packages → references/best-practices/packages.md#compilation-strategies
192└─ Sharing code between apps → references/best-practices/RULE.md#package-types
193```
194 
195### "How should I structure my monorepo?"
196 
197```
198Monorepo structure?
199├─ Standard layout (apps/, packages/) → references/best-practices/RULE.md
200├─ Package types (apps vs libraries) → references/best-practices/RULE.md#package-types
201├─ Creating internal packages → references/best-practices/packages.md
202├─ TypeScript configuration → references/best-practices/structure.md#typescript-configuration
203├─ ESLint configuration → references/best-practices/structure.md#eslint-configuration
204├─ Dependency management → references/best-practices/dependencies.md
205└─ Enforce package boundaries → references/boundaries/RULE.md
206```
207 
208### "I want to enforce architectural boundaries"
209 
210```
211Enforce boundaries?
212├─ Check for violations → turbo boundaries
213├─ Tag packages → references/boundaries/RULE.md#tags
214├─ Restrict which packages can import others → references/boundaries/RULE.md#rule-types
215└─ Prevent cross-package file imports → references/boundaries/RULE.md
216```
217 
218## Critical Anti-Patterns
219 
220### Using `turbo` Shorthand in Code
221 
222**`turbo run` is recommended in package.json scripts and CI pipelines.** The shorthand `turbo <task>` is intended for interactive terminal use.
223 
224```json
225// WRONG - using shorthand in package.json
226{
227  "scripts": {
228    "build": "turbo build",
229    "dev": "turbo dev"
230  }
231}
232 
233// CORRECT
234{
235  "scripts": {
236    "build": "turbo run build",
237    "dev": "turbo run dev"
238  }
239}
240```
241 
242```yaml
243# WRONG - using shorthand in CI
244- run: turbo build --affected
245 
246# CORRECT
247- run: turbo run build --affected
248```
249 
250### Root Scripts Bypassing Turbo
251 
252Root `package.json` scripts MUST delegate to `turbo run`, not run tasks directly.
253 
254```json
255// WRONG - bypasses turbo entirely
256{
257  "scripts": {
258    "build": "bun build",
259    "dev": "bun dev"
260  }
261}
262 
263// CORRECT - delegates to turbo
264{
265  "scripts": {
266    "build": "turbo run build",
267    "dev": "turbo run dev"
268  }
269}
270```
271 
272### Using `&&` to Chain Turbo Tasks
273 
274Don't chain turbo tasks with `&&`. Let turbo orchestrate.
275 
276```json
277// WRONG - turbo task not using turbo run
278{
279  "scripts": {
280    "changeset:publish": "bun build && changeset publish"
281  }
282}
283 
284// CORRECT
285{
286  "scripts": {
287    "changeset:publish": "turbo run build && changeset publish"
288  }
289}
290```
291 
292### `prebuild` Scripts That Manually Build Dependencies
293 
294Scripts like `prebuild` that manually build other packages bypass Turborepo's dependency graph.
295 
296```json
297// WRONG - manually building dependencies
298{
299  "scripts": {
300    "prebuild": "cd ../../packages/types && bun run build && cd ../utils && bun run build",
301    "build": "next build"
302  }
303}
304```
305 
306**However, the fix depends on whether workspace dependencies are declared:**
307 
3081. **If dependencies ARE declared** (e.g., `"@repo/types": "workspace:*"` in package.json), remove the `prebuild` script. Turbo's `dependsOn: ["^build"]` handles this automatically.
309 
3102. **If dependencies are NOT declared**, the `prebuild` exists because `^build` won't trigger without a dependency relationship. The fix is to:
311   - Add the dependency to package.json: `"@repo/types": "workspace:*"`
312   - Then remove the `prebuild` script
313 
314```json
315// CORRECT - declare dependency, let turbo handle build order
316// package.json
317{
318  "dependencies": {
319    "@repo/types": "workspace:*",
320    "@repo/utils": "workspace:*"
321  },
322  "scripts": {
323    "build": "next build"
324  }
325}
326 
327// turbo.json
328{
329  "tasks": {
330    "build": {
331      "dependsOn": ["^build"]
332    }
333  }
334}
335```
336 
337**Key insight:** `^build` only runs build in packages listed as dependencies. No dependency declaration = no automatic build ordering.
338 
339### Overly Broad `globalDependencies`
340 
341`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.
342 
343```json
344// WRONG - heavy hammer, affects all hashes
345{
346  "globalDependencies": ["**/.env.*local"]
347}
348 
349// BETTER - move to task-level inputs
350{
351  "globalDependencies": [".env"],
352  "tasks": {
353    "build": {
354      "inputs": ["$TURBO_DEFAULT$", ".env*"],
355      "outputs": ["dist/**"]
356    }
357  }
358}
359```
360 
361With `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:
362 
363```json
364// BEST - global.inputs with per-task exclusion
365{
366  "futureFlags": { "globalConfiguration": true },
367  "global": {
368    "inputs": [".env"]
369  },
370  "tasks": {
371    "build": { "outputs": ["dist/**"] },
372    "lint": {
373      "inputs": ["$TURBO_DEFAULT$", "!$TURBO_ROOT$/.env"]
374    }
375  }
376}
377```
378 
379### Repetitive Task Configuration
380 
381Look for repeated configuration across tasks that can be collapsed. Turborepo supports shared configuration patterns.
382 
383```json
384// WRONG - repetitive env and inputs across tasks
385{
386  "tasks": {
387    "build": {
388      "env": ["API_URL", "DATABASE_URL"],
389      "inputs": ["$TURBO_DEFAULT$", ".env*"]
390    },
391    "test": {
392      "env": ["API_URL", "DATABASE_URL"],
393      "inputs": ["$TURBO_DEFAULT$", ".env*"]
394    },
395    "dev": {
396      "env": ["API_URL", "DATABASE_URL"],
397      "inputs": ["$TURBO_DEFAULT$", ".env*"],
398      "cache": false,
399      "persistent": true
400    }
401  }
402}
403 
404// BETTER - use globalEnv and globalDependencies for shared config
405{
406  "globalEnv": ["API_URL", "DATABASE_URL"],
407  "globalDependencies": [".env*"],
408  "tasks": {
409    "build": {},
410    "test": {},
411    "dev": {
412      "cache": false,
413      "persistent": true
414    }
415  }
416}
417```
418 
419**When to use global vs task-level:**
420 
421- `globalEnv` / `globalDependencies` - affects ALL tasks, use for truly shared config
422- Task-level `env` / `inputs` - use when only specific tasks need it
423 
424### NOT an Anti-Pattern: Large `env` Arrays
425 
426A 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.
427 
428### Using `--parallel` Flag
429 
430The `--parallel` flag bypasses Turborepo's dependency graph. If tasks need parallel execution, configure `dependsOn` correctly instead.
431 
432```bash
433# WRONG - bypasses dependency graph
434turbo run lint --parallel
435 
436# CORRECT - configure tasks to allow parallel execution
437# In turbo.json, set dependsOn appropriately (or use transit nodes)
438turbo run lint
439```
440 
441### Package-Specific Task Overrides in Root turbo.json
442 
443When multiple packages need different task configurations, use **Package Configurations** (`turbo.json` in each package) instead of cluttering root `turbo.json` with `package#task` overrides.
444 
445```json
446// WRONG - root turbo.json with many package-specific overrides
447{
448  "tasks": {
449    "test": { "dependsOn": ["build"] },
450    "@repo/web#test": { "outputs": ["coverage/**"] },
451    "@repo/api#test": { "outputs": ["coverage/**"] },
452    "@repo/utils#test": { "outputs": [] },
453    "@repo/cli#test": { "outputs": [] },
454    "@repo/core#test": { "outputs": [] }
455  }
456}
457 
458// CORRECT - use Package Configurations
459// Root turbo.json - base config only
460{
461  "tasks": {
462    "test": { "dependsOn": ["build"] }
463  }
464}
465 
466// packages/web/turbo.json - package-specific override
467{
468  "extends": ["//"],
469  "tasks": {
470    "test": { "outputs": ["coverage/**"] }
471  }
472}
473 
474// packages/api/turbo.json
475{
476  "extends": ["//"],
477  "tasks": {
478    "test": { "outputs": ["coverage/**"] }
479  }
480}
481```
482 
483**Benefits of Package Configurations:**
484 
485- Keeps configuration close to the code it affects
486- Root turbo.json stays clean and focused on base patterns
487- Easier to understand what's special about each package
488- Works with `$TURBO_EXTENDS$` to inherit + extend arrays
489 
490**When to use `package#task` in root:**
491 
492- Single package needs a unique dependency (e.g., `"deploy": { "dependsOn": ["web#build"] }`)
493- Temporary override while migrating
494 
495See `references/configuration/RULE.md#package-configurations` for full details.
496 
497### Using `../` to Traverse Out of Package in `inputs`
498 
499Don't use relative paths like `../` to reference files outside the package. Use `$TURBO_ROOT$` instead.
500 
501```json
502// WRONG - traversing out of package
503{
504  "tasks": {
505    "build": {
506      "inputs": ["$TURBO_DEFAULT$", "../shared-config.json"]
507    }
508  }
509}
510 
511// CORRECT - use $TURBO_ROOT$ for repo root
512{
513  "tasks": {
514    "build": {
515      "inputs": ["$TURBO_DEFAULT$", "$TURBO_ROOT$/shared-config.json"]
516    }
517  }
518}
519```
520 
521### Missing `outputs` for File-Producing Tasks
522 
523**Before flagging missing `outputs`, check what the task actually produces:**
524 
5251. Read the package's script (e.g., `"build": "tsc"`, `"test": "vitest"`)
5262. Determine if it writes files to disk or only outputs to stdout
5273. Only flag if the task produces files that should be cached
528 
529```json
530// WRONG: build produces files but they're not cached
531{
532  "tasks": {
533    "build": {
534      "dependsOn": ["^build"]
535    }
536  }
537}
538 
539// CORRECT: build outputs are cached
540{
541  "tasks": {
542    "build": {
543      "dependsOn": ["^build"],
544      "outputs": ["dist/**"]
545    }
546  }
547}
548```
549 
550Common outputs by framework:
551 
552- Next.js: `[".next/**", "!.next/cache/**", "!.next/dev/**"]`
553- Vite/Rollup: `["dist/**"]`
554- tsc: `["dist/**"]` or custom `outDir`
555 
556**TypeScript `--noEmit` can still produce cache files:**
557 
558When `incremental: true` in tsconfig.json, `tsc --noEmit` writes `.tsbuildinfo` files even without emitting JS. Check the tsconfig before assuming no outputs:
559 
560```json
561// If tsconfig has incremental: true, tsc --noEmit produces cache files
562{
563  "tasks": {
564    "typecheck": {
565      "outputs": ["node_modules/.cache/tsbuildinfo.json"] // or wherever tsBuildInfoFile points
566    }
567  }
568}
569```
570 
571To determine correct outputs for TypeScript tasks:
572 
5731. Check if `incremental` or `composite` is enabled in tsconfig
5742. Check `tsBuildInfoFile` for custom cache location (default: alongside `outDir` or in project root)
5753. If no incremental mode, `tsc --noEmit` produces no files
576 
577### `^build` vs `build` Confusion
578 
579```json
580{
581  "tasks": {
582    // ^build = run build in DEPENDENCIES first (other packages this one imports)
583    "build": {
584      "dependsOn": ["^build"]
585    },
586    // build (no ^) = run build in SAME PACKAGE first
587    "test": {
588      "dependsOn": ["build"]
589    },
590    // pkg#task = specific package's task
591    "deploy": {
592      "dependsOn": ["web#build"]
593    }
594  }
595}
596```
597 
598### Environment Variables Not Hashed
599 
600```json
601// WRONG: API_URL changes won't cause rebuilds
602{
603  "tasks": {
604    "build": {
605      "outputs": ["dist/**"]
606    }
607  }
608}
609 
610// CORRECT: API_URL changes invalidate cache
611{
612  "tasks": {
613    "build": {
614      "outputs": ["dist/**"],
615      "env": ["API_URL", "API_KEY"]
616    }
617  }
618}
619```
620 
621### `.env` Files Not in Inputs
622 
623Turbo does NOT load `.env` files - your framework does. But Turbo needs to know about changes:
624 
625```json
626// WRONG: .env changes don't invalidate cache
627{
628  "tasks": {
629    "build": {
630      "env": ["API_URL"]
631    }
632  }
633}
634 
635// CORRECT: .env file changes invalidate cache
636{
637  "tasks": {
638    "build": {
639      "env": ["API_URL"],
640      "inputs": ["$TURBO_DEFAULT$", ".env", ".env.*"]
641    }
642  }
643}
644```
645 
646### Root `.env` File in Monorepo
647 
648A `.env` file at the repo root is an anti-pattern — even for small monorepos or starter templates. It creates implicit coupling between packages and makes it unclear which packages depend on which variables.
649 
650```
651// WRONG - root .env affects all packages implicitly
652my-monorepo/
653├── .env              # Which packages use this?
654├── apps/
655│   ├── web/
656│   └── api/
657└── packages/
658 
659// CORRECT - .env files in packages that need them
660my-monorepo/
661├── apps/
662│   ├── web/
663│   │   └── .env      # Clear: web needs DATABASE_URL
664│   └── api/
665│       └── .env      # Clear: api needs API_KEY
666└── packages/
667```
668 
669**Problems with root `.env`:**
670 
671- Unclear which packages consume which variables
672- All packages get all variables (even ones they don't need)
673- Cache invalidation is coarse-grained (root .env change invalidates everything)
674- Security risk: packages may accidentally access sensitive vars meant for others
675- Bad habits start small — starter templates should model correct patterns
676 
677**If you must share variables**, use `globalEnv` to be explicit about what's shared, and document why.
678 
679### Strict Mode Filtering CI Variables
680 
681By default, Turborepo filters environment variables to only those in `env`/`globalEnv`. CI variables may be missing:
682 
683```json
684// If CI scripts need GITHUB_TOKEN but it's not in env:
685{
686  "globalPassThroughEnv": ["GITHUB_TOKEN", "CI"],
687  "tasks": { ... }
688}
689```
690 
691Or use `--env-mode=loose` (not recommended for production).
692 
693### Shared Code in Apps (Should Be a Package)
694 
695```
696// WRONG: Shared code inside an app
697apps/
698  web/
699    shared/          # This breaks monorepo principles!
700      utils.ts
701 
702// CORRECT: Extract to a package
703packages/
704  utils/
705    src/utils.ts
706```
707 
708### Accessing Files Across Package Boundaries
709 
710```typescript
711// WRONG: Reaching into another package's internals
712import { Button } from "../../packages/ui/src/button";
713 
714// CORRECT: Install and import properly
715import { Button } from "@repo/ui/button";
716```
717 
718### Too Many Root Dependencies
719 
720```json
721// WRONG: App dependencies in root
722{
723  "dependencies": {
724    "react": "^18",
725    "next": "^14"
726  }
727}
728 
729// CORRECT: Only repo tools in root
730{
731  "devDependencies": {
732    "turbo": "latest"
733  }
734}
735```
736 
737## Common Task Configurations
738 
739### Standard Build Pipeline
740 
741```json
742{
743  "$schema": "https://v2-10-3-canary-4.turborepo.dev/schema.json",
744  "tasks": {
745    "build": {
746      "dependsOn": ["^build"],
747      "outputs": ["dist/**", ".next/**", "!.next/cache/**", "!.next/dev/**"]
748    },
749    "dev": {
750      "cache": false,
751      "persistent": true
752    }
753  }
754}
755```
756 
757Add a `transit` task if you have tasks that need parallel execution with cache invalidation (see below).
758 
759### Dev Task with `^dev` Pattern (for `turbo watch`)
760 
761A `dev` task with `dependsOn: ["^dev"]` and `persistent: false` in root turbo.json may look unusual but is **correct for `turbo watch` workflows**:
762 
763```json
764// Root turbo.json
765{
766  "tasks": {
767    "dev": {
768      "dependsOn": ["^dev"],
769      "cache": false,
770      "persistent": false  // Packages have one-shot dev scripts
771    }
772  }
773}
774 
775// Package turbo.json (apps/web/turbo.json)
776{
777  "extends": ["//"],
778  "tasks": {
779    "dev": {
780      "persistent": true  // Apps run long-running dev servers
781    }
782  }
783}
784```
785 
786**Why this works:**
787 
788- **Packages** (e.g., `@acme/db`, `@acme/validators`) have `"dev": "tsc"` — one-shot type generation that completes quickly
789- **Apps** override with `persistent: true` for actual dev servers (Next.js, etc.)
790- **`turbo watch`** re-runs the one-shot package `dev` scripts when source files change, keeping types in sync
791 
792**Intended usage:** Run `turbo watch dev` (not `turbo run dev`). Watch mode re-executes one-shot tasks on file changes while keeping persistent tasks running.
793 
794**Alternative pattern:** Use a separate task name like `prepare` or `generate` for one-shot dependency builds to make the intent clearer:
795 
796```json
797{
798  "tasks": {
799    "prepare": {
800      "dependsOn": ["^prepare"],
801      "outputs": ["dist/**"]
802    },
803    "dev": {
804      "dependsOn": ["prepare"],
805      "cache": false,
806      "persistent": true
807    }
808  }
809}
810```
811 
812### Transit Nodes for Parallel Tasks with Cache Invalidation
813 
814Some tasks can run in parallel (don't need built output from dependencies) but must invalidate cache when dependency source code changes.
815 
816**The problem with `dependsOn: ["^taskname"]`:**
817 
818- Forces sequential execution (slow)
819 
820**The problem with `dependsOn: []` (no dependencies):**
821 
822- Allows parallel execution (fast)
823- But cache is INCORRECT - changing dependency source won't invalidate cache
824 
825**Transit Nodes solve both:**
826 
827```json
828{
829  "tasks": {
830    "transit": { "dependsOn": ["^transit"] },
831    "my-task": { "dependsOn": ["transit"] }
832  }
833}
834```
835 
836The `transit` task creates dependency relationships without matching any actual script, so tasks run in parallel with correct cache invalidation.
837 
838**How to identify tasks that need this pattern:** Look for tasks that read source files from dependencies but don't need their build outputs.
839 
840### With Environment Variables
841 
842```json
843{
844  "globalEnv": ["NODE_ENV"],
845  "globalDependencies": [".env"],
846  "tasks": {
847    "build": {
848      "dependsOn": ["^build"],
849      "outputs": ["dist/**"],
850      "env": ["API_URL", "DATABASE_URL"]
851    }
852  }
853}
854```
855 
856With `futureFlags.globalConfiguration`, the same config moves global settings under `global` — and `.env` becomes a per-task input instead of a global hash input:
857 
858```json
859{
860  "futureFlags": { "globalConfiguration": true },
861  "global": {
862    "env": ["NODE_ENV"],
863    "inputs": [".env"]
864  },
865  "tasks": {
866    "build": {
867      "dependsOn": ["^build"],
868      "outputs": ["dist/**"],
869      "env": ["API_URL", "DATABASE_URL"]
870    }
871  }
872}
873```
874 
875## Reference Index
876 
877### Configuration
878 
879| File                                                                            | Purpose                                                                   |
880| ------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
881| [configuration/RULE.md](./references/configuration/RULE.md)                     | turbo.json overview, Package Configurations                               |
882| [configuration/tasks.md](./references/configuration/tasks.md)                   | dependsOn, outputs, inputs, env, cache, persistent                        |
883| [configuration/global-options.md](./references/configuration/global-options.md) | globalEnv, globalDependencies, global key, futureFlags, cacheDir, envMode |
884| [configuration/gotchas.md](./references/configuration/gotchas.md)               | Common configuration mistakes                                             |
885 
886### Caching
887 
888| File                                                            | Purpose                                      |
889| --------------------------------------------------------------- | -------------------------------------------- |
890| [caching/RULE.md](./references/caching/RULE.md)                 | How caching works, hash inputs               |
891| [caching/remote-cache.md](./references/caching/remote-cache.md) | Vercel Remote Cache, self-hosted, login/link |
892| [caching/gotchas.md](./references/caching/gotchas.md)           | Debugging cache misses, --summarize, --dry   |
893 
894### Environment Variables
895 
896| File                                                          | Purpose                                   |
897| ------------------------------------------------------------- | ----------------------------------------- |
898| [environment/RULE.md](./references/environment/RULE.md)       | env, globalEnv, passThroughEnv            |
899| [environment/modes.md](./references/environment/modes.md)     | Strict vs Loose mode, framework inference |
900| [environment/gotchas.md](./references/environment/gotchas.md) | .env files, CI issues                     |
901 
902### Filtering
903 
904| File                                                        | Purpose                  |
905| ----------------------------------------------------------- | ------------------------ |
906| [filtering/RULE.md](./references/filtering/RULE.md)         | --filter syntax overview |
907| [filtering/patterns.md](./references/filtering/patterns.md) | Common filter patterns   |
908 
909### CI/CD
910 
911| File                                                      | Purpose                         |
912| --------------------------------------------------------- | ------------------------------- |
913| [ci/RULE.md](./references/ci/RULE.md)                     | General CI principles           |
914| [ci/github-actions.md](./references/ci/github-actions.md) | Complete GitHub Actions setup   |
915| [ci/vercel.md](./references/ci/vercel.md)                 | Vercel deployment, turbo-ignore |
916| [ci/patterns.md](./references/ci/patterns.md)             | --affected, caching strategies  |
917 
918### CLI
919 
920| File                                            | Purpose                                       |
921| ----------------------------------------------- | --------------------------------------------- |
922| [cli/RULE.md](./references/cli/RULE.md)         | turbo run basics                              |
923| [cli/commands.md](./references/cli/commands.md) | turbo run flags, turbo-ignore, other commands |
924 
925### Best Practices
926 
927| File                                                                          | Purpose                                                         |
928| ----------------------------------------------------------------------------- | --------------------------------------------------------------- |
929| [best-practices/RULE.md](./references/best-practices/RULE.md)                 | Monorepo best practices overview                                |
930| [best-practices/structure.md](./references/best-practices/structure.md)       | Repository structure, workspace config, TypeScript/ESLint setup |
931| [best-practices/packages.md](./references/best-practices/packages.md)         | Creating internal packages, JIT vs Compiled, exports            |
932| [best-practices/dependencies.md](./references/best-practices/dependencies.md) | Dependency management, installing, version sync                 |
933 
934### Watch Mode
935 
936| File                                        | Purpose                                         |
937| ------------------------------------------- | ----------------------------------------------- |
938| [watch/RULE.md](./references/watch/RULE.md) | turbo watch, interruptible tasks, dev workflows |
939 
940### Boundaries (Experimental)
941 
942| File                                                  | Purpose                                               |
943| ----------------------------------------------------- | ----------------------------------------------------- |
944| [boundaries/RULE.md](./references/boundaries/RULE.md) | Enforce package isolation, tag-based dependency rules |
945 
946## Source Documentation
947 
948This skill is based on the official Turborepo documentation at:
949 
950- Source: `apps/docs/content/docs/` in the Turborepo repository
951- Live: https://turborepo.dev/docs
952