1# turbo.json Configuration Overview
2 
3Configuration reference for Turborepo. Full docs: https://turborepo.dev/docs/reference/configuration
4 
5## File Location
6 
7Root `turbo.json` lives at repo root, sibling to root `package.json`:
8 
9```
10my-monorepo/
11├── turbo.json        # Root configuration
12├── package.json
13└── packages/
14    └── web/
15        ├── turbo.json  # Package Configuration (optional)
16        └── package.json
17```
18 
19## Always Prefer Package Tasks Over Root Tasks
20 
21**Always use package tasks. Only use Root Tasks if you cannot succeed with package tasks.**
22 
23Package tasks enable parallelization, individual caching, and filtering. Define scripts in each package's `package.json`:
24 
25```json
26// packages/web/package.json
27{
28  "scripts": {
29    "build": "next build",
30    "lint": "eslint .",
31    "test": "vitest",
32    "typecheck": "tsc --noEmit"
33  }
34}
35 
36// packages/api/package.json
37{
38  "scripts": {
39    "build": "tsc",
40    "lint": "eslint .",
41    "test": "vitest",
42    "typecheck": "tsc --noEmit"
43  }
44}
45```
46 
47```json
48// Root package.json - delegates to turbo
49{
50  "scripts": {
51    "build": "turbo run build",
52    "lint": "turbo run lint",
53    "test": "turbo run test",
54    "typecheck": "turbo run typecheck"
55  }
56}
57```
58 
59When you run `turbo run lint`, Turborepo finds all packages with a `lint` script and runs them **in parallel**.
60 
61**Root Tasks are a fallback**, not the default. Only use them for tasks that truly cannot run per-package (e.g., repo-level CI scripts, workspace-wide config generation).
62 
63```json
64// AVOID: Task logic in root defeats parallelization
65{
66  "scripts": {
67    "lint": "eslint apps/web && eslint apps/api && eslint packages/ui"
68  }
69}
70```
71 
72## Basic Structure
73 
74```json
75{
76  "$schema": "https://v2-9-12.turborepo.dev/schema.json",
77  "globalEnv": ["CI"],
78  "globalDependencies": ["tsconfig.json"],
79  "tasks": {
80    "build": {
81      "dependsOn": ["^build"],
82      "outputs": ["dist/**"]
83    },
84    "dev": {
85      "cache": false,
86      "persistent": true
87    }
88  }
89}
90```
91 
92The `$schema` key enables IDE autocompletion and validation.
93 
94### With `futureFlags.globalConfiguration`
95 
96When the `globalConfiguration` future flag is enabled, global options move under a `global` key with cleaner names:
97 
98```json
99{
100  "$schema": "https://v2-9-12.turborepo.dev/schema.json",
101  "futureFlags": { "globalConfiguration": true },
102  "global": {
103    "inputs": ["tsconfig.json"],
104    "env": ["CI"],
105    "ui": "tui"
106  },
107  "tasks": {
108    "build": {
109      "dependsOn": ["^build"],
110      "outputs": ["dist/**"]
111    }
112  }
113}
114```
115 
116See the [global options reference](./global-options.md) for the full rename mapping and behavior changes.
117 
118## Configuration Sections
119 
120**Global options** - Settings affecting all tasks:
121 
122- Without flag: `globalEnv`, `globalDependencies`, `globalPassThroughEnv`, `cacheDir`, `daemon`, `envMode`, `ui`, `remoteCache`
123- With `globalConfiguration` flag: all of the above move under the `global` key (see [global options](./global-options.md))
124 
125**Task definitions** - Per-task settings in `tasks` object:
126 
127- `dependsOn`, `outputs`, `inputs`, `env`
128- `cache`, `persistent`, `interactive`, `outputLogs`
129 
130## Package Configurations
131 
132Use `turbo.json` in individual packages to override root settings:
133 
134```json
135// packages/web/turbo.json
136{
137  "extends": ["//"],
138  "tasks": {
139    "build": {
140      "outputs": [".next/**", "!.next/cache/**"]
141    }
142  }
143}
144```
145 
146The `"extends": ["//"]` is required - it references the root configuration.
147 
148**When to use Package Configurations:**
149 
150- Framework-specific outputs (Next.js, Vite, etc.)
151- Package-specific env vars
152- Different caching rules for specific packages
153- Keeping framework config close to the framework code
154 
155### Extending from Other Packages
156 
157You can extend from config packages instead of just root:
158 
159```json
160// packages/web/turbo.json
161{
162  "extends": ["//", "@repo/turbo-config"]
163}
164```
165 
166### Adding to Inherited Arrays with `$TURBO_EXTENDS$`
167 
168By default, array fields in Package Configurations **replace** root values. Use `$TURBO_EXTENDS$` to **append** instead:
169 
170```json
171// Root turbo.json
172{
173  "tasks": {
174    "build": {
175      "outputs": ["dist/**"]
176    }
177  }
178}
179```
180 
181```json
182// packages/web/turbo.json
183{
184  "extends": ["//"],
185  "tasks": {
186    "build": {
187      // Inherits "dist/**" from root, adds ".next/**"
188      "outputs": ["$TURBO_EXTENDS$", ".next/**", "!.next/cache/**"]
189    }
190  }
191}
192```
193 
194Without `$TURBO_EXTENDS$`, outputs would only be `[".next/**", "!.next/cache/**"]`.
195 
196**Works with:**
197 
198- `dependsOn`
199- `env`
200- `inputs`
201- `outputs`
202- `passThroughEnv`
203- `with`
204 
205### Excluding Tasks from Packages
206 
207Use `extends: false` to exclude a task from a package:
208 
209```json
210// packages/ui/turbo.json
211{
212  "extends": ["//"],
213  "tasks": {
214    "e2e": {
215      "extends": false // UI package doesn't have e2e tests
216    }
217  }
218}
219```
220 
221## `turbo.jsonc` for Comments
222 
223Use `turbo.jsonc` extension to add comments with IDE support:
224 
225```jsonc
226// turbo.jsonc
227{
228  "tasks": {
229    "build": {
230      // Next.js outputs
231      "outputs": [".next/**", "!.next/cache/**"]
232    }
233  }
234}
235```
236