1# How Turborepo Caching Works
2 
3Turborepo's core principle: **never do the same work twice**.
4 
5## The Cache Equation
6 
7```
8fingerprint(inputs) → stored outputs
9```
10 
11If inputs haven't changed, restore outputs from cache instead of re-running the task.
12 
13## What Determines the Cache Key
14 
15### Global Hash Inputs
16 
17These affect ALL tasks in the repo:
18 
19- `package-lock.json` / `yarn.lock` / `pnpm-lock.yaml`
20- Files listed in `globalDependencies` (or `global.env` when using `globalConfiguration`)
21- Environment variables in `globalEnv` (or `global.env`)
22- `turbo.json` configuration
23 
24```json
25{
26  "globalDependencies": [".env", "tsconfig.base.json"],
27  "globalEnv": ["CI", "NODE_ENV"]
28}
29```
30 
31### Task Hash Inputs
32 
33These affect specific tasks:
34 
35- All files in the package (unless filtered by `inputs`)
36- `package.json` contents
37- Environment variables in task's `env` key
38- Task configuration (command, outputs, dependencies)
39- Hashes of dependent tasks (`dependsOn`)
40- Files from `global.inputs` (when using `futureFlags.globalConfiguration` — see below)
41 
42```json
43{
44  "tasks": {
45    "build": {
46      "dependsOn": ["^build"],
47      "inputs": ["src/**", "package.json", "tsconfig.json"],
48      "env": ["API_URL"]
49    }
50  }
51}
52```
53 
54### How `global.inputs` Changes the Hash Equation
55 
56When `futureFlags.globalConfiguration` is enabled, `global.inputs` files are **not** part of the global hash. Instead, they are prepended to every task's `inputs` and folded into the **task hash**. This is a fundamental change from `globalDependencies`.
57 
58**With `globalDependencies` (default):**
59 
60```
61task cache key = hash(global hash, task hash)
62                      ↑ includes globalDependencies file hashes
63```
64 
65Changing a `globalDependencies` file invalidates **every** task, regardless of task-level `inputs`. There is no way for a task to opt out.
66 
67**With `global.inputs` (`futureFlags.globalConfiguration`):**
68 
69```
70task cache key = hash(global hash, task hash)
71                                   ↑ includes global.inputs file hashes (merged with task inputs)
72```
73 
74`global.inputs` files are merged into each task's input globs. This means:
75 
76- Tasks can **exclude** specific global files with negation globs: `"inputs": ["$TURBO_DEFAULT$", "!$TURBO_ROOT$/tsconfig.json"]`
77- The global hash is smaller (it still includes lockfile, engines, `global.env`, etc. — but not file hashes from `global.inputs`)
78- The task hash correctly includes the global input file hashes alongside the task's own inputs
79 
80```json
81{
82  "futureFlags": { "globalConfiguration": true },
83  "global": {
84    "inputs": ["tsconfig.json", ".env"]
85  },
86  "tasks": {
87    "build": {
88      "outputs": ["dist/**"]
89    },
90    "lint": {
91      "inputs": ["$TURBO_DEFAULT$", "!$TURBO_ROOT$/tsconfig.json"]
92    }
93  }
94}
95```
96 
97In this example, changing `tsconfig.json` invalidates `build` (it's in the task's inputs) but **not** `lint` (which explicitly excludes it). With `globalDependencies`, both would have been invalidated.
98 
99## What Gets Cached
100 
1011. **File outputs** - files/directories specified in `outputs`
1022. **Task logs** - stdout/stderr for replay on cache hit
103 
104```json
105{
106  "tasks": {
107    "build": {
108      "outputs": ["dist/**", ".next/**"]
109    }
110  }
111}
112```
113 
114## Local Cache Location
115 
116```
117.turbo/cache/
118├── <hash1>.tar.zst    # compressed outputs
119├── <hash2>.tar.zst
120└── ...
121```
122 
123Add `.turbo` to `.gitignore`.
124 
125## Cache Restoration
126 
127On cache hit, Turborepo:
128 
1291. Extracts archived outputs to their original locations
1302. Replays the logged stdout/stderr
1313. Reports the task as cached (shows `FULL TURBO` in output)
132 
133## Example Flow
134 
135```bash
136# First run - executes build, caches result
137turbo build
138# → packages/ui: cache miss, executing...
139# → packages/web: cache miss, executing...
140 
141# Second run - same inputs, restores from cache
142turbo build
143# → packages/ui: cache hit, replaying output
144# → packages/web: cache hit, replaying output
145# → FULL TURBO
146```
147 
148## Key Points
149 
150- Cache is content-addressed (based on input hash, not timestamps)
151- Empty `outputs` array means task runs but nothing is cached
152- Tasks without `outputs` key cache nothing (use `"outputs": []` to be explicit)
153- Cache is invalidated when ANY input changes
154