1# Task Configuration Reference
2 
3Full docs: https://turborepo.dev/docs/reference/configuration#tasks
4 
5## dependsOn
6 
7Controls task execution order.
8 
9```json
10{
11  "tasks": {
12    "build": {
13      "dependsOn": [
14        "^build", // Dependencies' build tasks first
15        "codegen", // Same package's codegen task first
16        "shared#build" // Specific package's build task
17      ]
18    }
19  }
20}
21```
22 
23| Syntax     | Meaning                              |
24| ---------- | ------------------------------------ |
25| `^task`    | Run `task` in all dependencies first |
26| `task`     | Run `task` in same package first     |
27| `pkg#task` | Run specific package's task first    |
28 
29The `^` prefix is crucial - without it, you're referencing the same package.
30 
31### Transit Nodes for Parallel Tasks
32 
33For tasks like `lint` and `check-types` that can run in parallel but need dependency-aware caching:
34 
35```json
36{
37  "tasks": {
38    "transit": { "dependsOn": ["^transit"] },
39    "lint": { "dependsOn": ["transit"] },
40    "check-types": { "dependsOn": ["transit"] }
41  }
42}
43```
44 
45**DO NOT use `dependsOn: ["^lint"]`** - this forces sequential execution.
46**DO NOT use `dependsOn: []`** - this breaks cache invalidation.
47 
48The `transit` task creates dependency relationships without running anything (no matching script), so tasks run in parallel with correct caching.
49 
50## outputs
51 
52Glob patterns for files to cache. **If omitted, nothing is cached.**
53 
54```json
55{
56  "tasks": {
57    "build": {
58      "outputs": ["dist/**", "build/**"]
59    }
60  }
61}
62```
63 
64**Framework examples:**
65 
66```json
67// Next.js
68"outputs": [".next/**", "!.next/cache/**"]
69 
70// Vite
71"outputs": ["dist/**"]
72 
73// TypeScript (tsc)
74"outputs": ["dist/**", "*.tsbuildinfo"]
75 
76// No file outputs (lint, typecheck)
77"outputs": []
78```
79 
80Use `!` prefix to exclude patterns from caching.
81 
82## inputs
83 
84Files considered when calculating task hash. Defaults to all tracked files in package.
85 
86```json
87{
88  "tasks": {
89    "test": {
90      "inputs": ["src/**", "tests/**", "vitest.config.ts"]
91    }
92  }
93}
94```
95 
96**Special values:**
97 
98| Value                 | Meaning                                 |
99| --------------------- | --------------------------------------- |
100| `$TURBO_DEFAULT$`     | Include default inputs, then add/remove |
101| `$TURBO_ROOT$/<path>` | Reference files from repo root          |
102 
103```json
104{
105  "tasks": {
106    "build": {
107      "inputs": [
108        "$TURBO_DEFAULT$",
109        "!README.md",
110        "$TURBO_ROOT$/tsconfig.base.json"
111      ]
112    }
113  }
114}
115```
116 
117### Interaction with `global.inputs`
118 
119When `futureFlags.globalConfiguration` is enabled, files listed in `global.inputs` are prepended to every task's `inputs`. The combined list is then used to compute the task hash.
120 
121This is different from `globalDependencies`, where files were hashed into the **global** hash and could not be influenced by task-level `inputs`.
122 
123**With `globalDependencies` (old behavior):**
124 
125- `globalDependencies` files contribute to the global hash
126- Task `inputs` only control which **package** files are hashed
127- There is no way for a task to "opt out" of a `globalDependencies` file
128 
129**With `global.inputs` (new behavior):**
130 
131- `global.inputs` files are merged into each task's `inputs` globs
132- Task `inputs` and `global.inputs` are combined, then the full list is hashed into the **task** hash
133- Tasks can exclude specific global files with negation globs
134 
135```json
136{
137  "futureFlags": { "globalConfiguration": true },
138  "global": {
139    "inputs": ["tsconfig.json", ".env"]
140  },
141  "tasks": {
142    "build": {},
143    "lint": {
144      "inputs": ["$TURBO_DEFAULT$", "!$TURBO_ROOT$/.env"]
145    }
146  }
147}
148```
149 
150In this example:
151 
152- `build` hashes all package files + `tsconfig.json` + `.env` (from `global.inputs`)
153- `lint` hashes all package files + `tsconfig.json`, but **excludes** `.env` because of the negation glob
154 
155Tasks with no explicit `inputs` key still hash all package files (the default behavior) plus the `global.inputs` files.
156 
157## env
158 
159Environment variables to include in task hash.
160 
161```json
162{
163  "tasks": {
164    "build": {
165      "env": [
166        "API_URL",
167        "NEXT_PUBLIC_*", // Wildcard matching
168        "!DEBUG" // Exclude from hash
169      ]
170    }
171  }
172}
173```
174 
175Variables listed here affect cache hits - changing the value invalidates cache.
176 
177## cache
178 
179Enable/disable caching for a task. Default: `true`.
180 
181```json
182{
183  "tasks": {
184    "dev": { "cache": false },
185    "deploy": { "cache": false }
186  }
187}
188```
189 
190Disable for: dev servers, deploy commands, tasks with side effects.
191 
192## persistent
193 
194Mark long-running tasks that don't exit. Default: `false`.
195 
196```json
197{
198  "tasks": {
199    "dev": {
200      "cache": false,
201      "persistent": true
202    }
203  }
204}
205```
206 
207Required for dev servers - without it, dependent tasks wait forever.
208 
209## interactive
210 
211Allow task to receive stdin input. Default: `false`.
212 
213```json
214{
215  "tasks": {
216    "login": {
217      "cache": false,
218      "interactive": true
219    }
220  }
221}
222```
223 
224## outputLogs
225 
226Control when logs are shown. Options: `full`, `hash-only`, `new-only`, `errors-only`, `none`.
227 
228```json
229{
230  "tasks": {
231    "build": {
232      "outputLogs": "new-only" // Only show logs on cache miss
233    }
234  }
235}
236```
237 
238## with
239 
240Run tasks alongside this task. For long-running tasks that need runtime dependencies.
241 
242```json
243{
244  "tasks": {
245    "dev": {
246      "with": ["api#dev"],
247      "persistent": true,
248      "cache": false
249    }
250  }
251}
252```
253 
254Unlike `dependsOn`, `with` runs tasks concurrently (not sequentially). Use for dev servers that need other services running.
255 
256## interruptible
257 
258Allow `turbo watch` to restart the task on changes. Default: `false`.
259 
260```json
261{
262  "tasks": {
263    "dev": {
264      "persistent": true,
265      "interruptible": true,
266      "cache": false
267    }
268  }
269}
270```
271 
272Use for dev servers that don't automatically detect dependency changes.
273 
274## description
275 
276Human-readable description of the task.
277 
278```json
279{
280  "tasks": {
281    "build": {
282      "description": "Compiles the application for production deployment"
283    }
284  }
285}
286```
287 
288For documentation only - doesn't affect execution or caching.
289 
290## passThroughEnv
291 
292Environment variables available at runtime but NOT included in cache hash.
293 
294```json
295{
296  "tasks": {
297    "build": {
298      "passThroughEnv": ["AWS_SECRET_KEY", "GITHUB_TOKEN"]
299    }
300  }
301}
302```
303 
304**Warning**: Changes to these vars won't cause cache misses. Use `env` if changes should invalidate cache.
305 
306## extends (Package Configuration only)
307 
308Control task inheritance in Package Configurations.
309 
310```json
311// packages/ui/turbo.json
312{
313  "extends": ["//"],
314  "tasks": {
315    "lint": {
316      "extends": false // Exclude from this package
317    }
318  }
319}
320```
321 
322| Value            | Behavior                                                       |
323| ---------------- | -------------------------------------------------------------- |
324| `true` (default) | Inherit from root turbo.json                                   |
325| `false`          | Exclude task from package, or define fresh without inheritance |
326