1# Configuration Gotchas
2 
3Common mistakes and how to fix them.
4 
5## #1 Root Scripts Not Using `turbo run`
6 
7Root `package.json` scripts for turbo tasks MUST use `turbo run`, not direct commands.
8 
9```json
10// WRONG - bypasses turbo, no parallelization or caching
11{
12  "scripts": {
13    "build": "bun build",
14    "dev": "bun dev"
15  }
16}
17 
18// CORRECT - delegates to turbo
19{
20  "scripts": {
21    "build": "turbo run build",
22    "dev": "turbo run dev"
23  }
24}
25```
26 
27**Why this matters:** Running `bun build` or `npm run build` at root bypasses Turborepo entirely - no parallelization, no caching, no dependency graph awareness.
28 
29## #2 Using `&&` to Chain Turbo Tasks
30 
31Don't use `&&` to chain tasks that turbo should orchestrate.
32 
33```json
34// WRONG - changeset:publish chains turbo task with non-turbo command
35{
36  "scripts": {
37    "changeset:publish": "bun build && changeset publish"
38  }
39}
40 
41// CORRECT - use turbo run, let turbo handle dependencies
42{
43  "scripts": {
44    "changeset:publish": "turbo run build && changeset publish"
45  }
46}
47```
48 
49If the second command (`changeset publish`) depends on build outputs, the turbo task should run through turbo to get caching and parallelization benefits.
50 
51## #3 Overly Broad globalDependencies
52 
53`globalDependencies` affects hash for ALL tasks in ALL packages. Be specific.
54 
55```json
56// WRONG - affects all hashes
57{
58  "globalDependencies": ["**/.env.*local"]
59}
60 
61// CORRECT - move to specific tasks that need it
62{
63  "globalDependencies": [".env"],
64  "tasks": {
65    "build": {
66      "inputs": ["$TURBO_DEFAULT$", ".env*"],
67      "outputs": ["dist/**"]
68    }
69  }
70}
71```
72 
73**Why this matters:** `**/.env.*local` matches .env files in ALL packages, causing unnecessary cache invalidation. Instead:
74 
75- Use `globalDependencies` only for truly global files (root `.env`)
76- Use task-level `inputs` for package-specific .env files with `$TURBO_DEFAULT$` to preserve default behavior
77 
78With `futureFlags.globalConfiguration`, this is less of a concern because `global.inputs` acts as implicit task inputs — tasks can opt out of specific files with negation globs. But keeping the list focused is still good practice.
79 
80## #4 Repetitive Task Configuration
81 
82Look for repeated configuration across tasks that can be collapsed.
83 
84```json
85// WRONG - repetitive env and inputs across tasks
86{
87  "tasks": {
88    "build": {
89      "env": ["API_URL", "DATABASE_URL"],
90      "inputs": ["$TURBO_DEFAULT$", ".env*"]
91    },
92    "test": {
93      "env": ["API_URL", "DATABASE_URL"],
94      "inputs": ["$TURBO_DEFAULT$", ".env*"]
95    }
96  }
97}
98 
99// BETTER - use globalEnv and globalDependencies
100{
101  "globalEnv": ["API_URL", "DATABASE_URL"],
102  "globalDependencies": [".env*"],
103  "tasks": {
104    "build": {},
105    "test": {}
106  }
107}
108```
109 
110**When to use global vs task-level:**
111 
112- `globalEnv` / `globalDependencies` - affects ALL tasks, use for truly shared config
113- Task-level `env` / `inputs` - use when only specific tasks need it
114 
115## #5 Using `../` to Traverse Out of Package in `inputs`
116 
117Don't use relative paths like `../` to reference files outside the package. Use `$TURBO_ROOT$` instead.
118 
119```json
120// WRONG - traversing out of package
121{
122  "tasks": {
123    "build": {
124      "inputs": ["$TURBO_DEFAULT$", "../shared-config.json"]
125    }
126  }
127}
128 
129// CORRECT - use $TURBO_ROOT$ for repo root
130{
131  "tasks": {
132    "build": {
133      "inputs": ["$TURBO_DEFAULT$", "$TURBO_ROOT$/shared-config.json"]
134    }
135  }
136}
137```
138 
139## #6 MOST COMMON MISTAKE: Creating Root Tasks
140 
141**Prefer package tasks over Root Tasks.**
142 
143When you need to create a task (build, lint, test, typecheck, etc.), default to package tasks:
144 
1451. Add the script to **each relevant package's** `package.json`
1462. Register the task in root `turbo.json`
1473. Root `package.json` only contains `turbo run <task>`
148 
149```json
150// WRONG - DO NOT DO THIS
151// Root package.json with task logic
152{
153  "scripts": {
154    "build": "cd apps/web && next build && cd ../api && tsc",
155    "lint": "eslint apps/ packages/",
156    "test": "vitest"
157  }
158}
159 
160// CORRECT - DO THIS
161// apps/web/package.json
162{ "scripts": { "build": "next build", "lint": "eslint .", "test": "vitest" } }
163 
164// apps/api/package.json
165{ "scripts": { "build": "tsc", "lint": "eslint .", "test": "vitest" } }
166 
167// packages/ui/package.json
168{ "scripts": { "build": "tsc", "lint": "eslint .", "test": "vitest" } }
169 
170// Root package.json - ONLY delegates
171{ "scripts": { "build": "turbo run build", "lint": "turbo run lint", "test": "turbo run test" } }
172 
173// turbo.json - register tasks
174{
175  "tasks": {
176    "build": { "dependsOn": ["^build"], "outputs": ["dist/**"] },
177    "lint": {},
178    "test": {}
179  }
180}
181```
182 
183**Why this matters:**
184 
185- Package tasks run in **parallel** across all packages
186- Each package's output is cached **individually**
187- You can **filter** to specific packages: `turbo run test --filter=web`
188 
189Root Tasks (`//#taskname`) defeat all these benefits when a task can live in packages. Only use them for tasks that truly cannot exist in any package, such as Vitest Projects' `//#test`, repo-wide release scripts, or tooling that does not invoke `turbo` itself.
190 
191## #7 Tasks That Need Parallel Execution + Cache Invalidation
192 
193Some tasks can run in parallel (don't need built output from dependencies) but must still invalidate cache when dependency source code changes. Using `dependsOn: ["^taskname"]` forces sequential execution. Using no dependencies breaks cache invalidation.
194 
195**Use Transit Nodes for these tasks:**
196 
197```json
198// WRONG - forces sequential execution (SLOW)
199"my-task": {
200  "dependsOn": ["^my-task"]
201}
202 
203// ALSO WRONG - no dependency awareness (INCORRECT CACHING)
204"my-task": {}
205 
206// CORRECT - use Transit Nodes for parallel + correct caching
207{
208  "tasks": {
209    "transit": { "dependsOn": ["^transit"] },
210    "my-task": { "dependsOn": ["transit"] }
211  }
212}
213```
214 
215**Why Transit Nodes work:**
216 
217- `transit` creates dependency relationships without matching any actual script
218- Tasks that depend on `transit` gain dependency awareness
219- Since `transit` completes instantly (no script), tasks run in parallel
220- Cache correctly invalidates when dependency source code changes
221 
222**How to identify tasks that need this pattern:** Look for tasks that read source files from dependencies but don't need their build outputs.
223 
224## Missing outputs for File-Producing Tasks
225 
226**Before flagging missing `outputs`, check what the task actually produces:**
227 
2281. Read the package's script (e.g., `"build": "tsc"`, `"test": "vitest"`)
2292. Determine if it writes files to disk or only outputs to stdout
2303. Only flag if the task produces files that should be cached
231 
232```json
233// WRONG - build produces files but they're not cached
234"build": {
235  "dependsOn": ["^build"]
236}
237 
238// CORRECT - outputs are cached
239"build": {
240  "dependsOn": ["^build"],
241  "outputs": ["dist/**"]
242}
243```
244 
245No `outputs` key is fine for stdout-only tasks. For file-producing tasks, missing `outputs` means Turbo has nothing to cache.
246 
247## Forgetting ^ in dependsOn
248 
249```json
250// WRONG - looks for "build" in SAME package (infinite loop or missing)
251"build": {
252  "dependsOn": ["build"]
253}
254 
255// CORRECT - runs dependencies' build first
256"build": {
257  "dependsOn": ["^build"]
258}
259```
260 
261The `^` means "in dependency packages", not "in this package".
262 
263## Missing persistent on Dev Tasks
264 
265```json
266// WRONG - dependent tasks hang waiting for dev to "finish"
267"dev": {
268  "cache": false
269}
270 
271// CORRECT
272"dev": {
273  "cache": false,
274  "persistent": true
275}
276```
277 
278## Package Config Missing extends
279 
280```json
281// WRONG - packages/web/turbo.json
282{
283  "tasks": {
284    "build": { "outputs": [".next/**"] }
285  }
286}
287 
288// CORRECT
289{
290  "extends": ["//"],
291  "tasks": {
292    "build": { "outputs": [".next/**"] }
293  }
294}
295```
296 
297Without `"extends": ["//"]`, Package Configurations are invalid.
298 
299## Root Tasks Need Special Syntax
300 
301To run a task defined only in root `package.json`:
302 
303```bash
304# WRONG
305turbo run format
306 
307# CORRECT
308turbo run //#format
309```
310 
311And in dependsOn:
312 
313```json
314"build": {
315  "dependsOn": ["//#codegen"]  // Root package's codegen
316}
317```
318 
319## Overwriting Default Inputs
320 
321```json
322// WRONG - only watches test files, ignores source changes
323"test": {
324  "inputs": ["tests/**"]
325}
326 
327// CORRECT - extends defaults, adds test files
328"test": {
329  "inputs": ["$TURBO_DEFAULT$", "tests/**"]
330}
331```
332 
333Without `$TURBO_DEFAULT$`, you replace all default file watching.
334 
335## Excluding `global.inputs` Without `$TURBO_DEFAULT$`
336 
337When using `futureFlags.globalConfiguration`, `global.inputs` values are prepended to every task's inputs. If you want to exclude a global input from a specific task, you **must** include `$TURBO_DEFAULT$` to preserve default file hashing.
338 
339```json
340// WRONG - task hashes NO files at all (global input cancelled, no defaults)
341"build": {
342  "inputs": ["!$TURBO_ROOT$/config.txt"]
343}
344 
345// CORRECT - task hashes all package files, minus config.txt
346"build": {
347  "inputs": ["$TURBO_DEFAULT$", "!$TURBO_ROOT$/config.txt"]
348}
349```
350 
351Without `$TURBO_DEFAULT$`, the only inclusion glob comes from `global.inputs`, which the negation cancels out. The task ends up with no inclusions and no default file hashing, so it hashes nothing. Changes to source files won't cause cache misses.
352 
353## Caching Tasks with Side Effects
354 
355```json
356// WRONG - deploy might be skipped on cache hit
357"deploy": {
358  "dependsOn": ["build"]
359}
360 
361// CORRECT
362"deploy": {
363  "dependsOn": ["build"],
364  "cache": false
365}
366```
367 
368Always disable cache for deploy, publish, or mutation tasks.
369