0
# Caching & Performance
1

2
Local and remote caching configuration with performance profiling, analysis tools, and advanced cache management for optimal build performance.
3

4
## Capabilities
5

6
### Cache Configuration
7

8
Control how Turbo caches task results locally and remotely for maximum performance.
9

10
```bash { .api }
11
# Cache control options
12
--cache <config>                   # Cache configuration string
13
--force                           # Ignore existing cache, force execution
14
--no-cache                        # Disable all caching
15
--remote-only                     # Use only remote cache
16
--remote-cache-read-only          # Read-only remote cache access
17

18
# Cache behavior examples
19
turbo run build --cache=local:rw,remote:r
20
turbo run build --force
21
turbo run build --no-cache
22
turbo run build --remote-only
23
```
24

25
**Cache Configuration Syntax:**
26

27
```bash { .api }
28
# Cache configuration format: <location>:<permissions>
29
local:rw        # Local cache: read and write
30
local:r         # Local cache: read only
31
local:w         # Local cache: write only
32
remote:rw       # Remote cache: read and write  
33
remote:r        # Remote cache: read only
34
remote:w        # Remote cache: write only
35

36
# Combined configurations (comma-separated)
37
local:rw,remote:r      # Local read/write, remote read-only
38
local:r,remote:rw      # Local read-only, remote read/write
39
```
40

41
**Usage Examples:**
42

43
```bash
44
# Use only local cache
45
turbo run build --cache=local:rw
46

47
# Use remote cache for reading, local for writing
48
turbo run build --cache=local:rw,remote:r
49

50
# Force execution and update both caches
51
turbo run build --cache=local:w,remote:w --force
52

53
# Read from remote, write to local only
54
turbo run build --cache=local:w,remote:r
55
```
56

57
### Cache Directory Management
58

59
Configure cache storage location and behavior.
60

61
```bash { .api }
62
# Cache directory options
63
--cache-dir <path>                 # Override cache directory location
64
--cache-workers <number>           # Concurrent cache operations (default: 10)
65

66
# Cache directory examples
67
turbo run build --cache-dir=./custom-cache
68
turbo run build --cache-workers=20
69
```
70

71
**Usage Examples:**
72

73
```bash
74
# Use custom cache directory
75
turbo run build --cache-dir=/tmp/turbo-cache
76

77
# Increase cache operation concurrency
78
turbo run build --cache-workers=20
79

80
# Combine with remote cache settings
81
turbo run build --cache-dir=./build-cache --remote-only
82
```
83

84
### Performance Profiling
85

86
Generate detailed performance profiles and traces for analyzing build performance.
87

88
```bash { .api }
89
# Performance profiling options
90
--profile <file>                   # Save performance profile with identifiable data
91
--anon-profile <file>              # Save anonymous performance profile
92
--trace <file>                     # Save performance trace (global option)
93

94
# Profiling examples
95
turbo run build --profile=build-profile.json
96
turbo run build --anon-profile=anon-build-profile.json
97
turbo run build --trace=build-trace.json
98
```
99

100
**Usage Examples:**
101

102
```bash
103
# Generate detailed profile for performance analysis
104
turbo run build --profile=profiles/build-$(date +%Y%m%d).json
105

106
# Generate anonymous profile for sharing
107
turbo run build --anon-profile=anon-profile.json
108

109
# Capture trace data for Chrome DevTools
110
turbo run build --trace=chrome-trace.json
111

112
# Profile specific filtered packages
113
turbo run build --filter="@myorg/slow-package" --profile=slow-package.json
114
```
115

116
### Task Execution Graph
117

118
Visualize and export task dependency graphs for analysis and debugging.
119

120
```bash { .api }
121
--graph <file>                     # Generate task execution graph
122
--graph                           # Output graph to stdout (DOT format)
123

124
# Supported graph formats
125
graph.svg          # SVG image
126
graph.png          # PNG image  
127
graph.jpg          # JPEG image
128
graph.pdf          # PDF document
129
graph.json         # JSON data
130
graph.html         # Interactive HTML
131
graph.mermaid      # Mermaid diagram
132
graph.dot          # DOT/Graphviz format
133
```
134

135
**Usage Examples:**
136

137
```bash
138
# Generate interactive HTML graph
139
turbo run build --graph=task-graph.html
140

141
# Generate SVG for documentation
142
turbo run build test lint --graph=full-pipeline.svg
143

144
# Output DOT format to stdout for further processing
145
turbo run build --graph | dot -Tpng > custom-graph.png
146

147
# Generate JSON for programmatic analysis
148
turbo run build --filter="@myorg/*" --graph=org-tasks.json
149
```
150

151
### Run Summaries
152

153
Generate comprehensive summaries of task execution including timing, cache hits, and performance metrics.
154

155
```bash { .api }
156
--summarize                        # Generate execution summary
157
--summarize=true                   # Explicit enable
158
--summarize=false                  # Explicit disable
159

160
# Summary examples
161
turbo run build --summarize
162
turbo run build test --summarize --profile=detailed.json
163
```
164

165
**Usage Examples:**
166

167
```bash
168
# Generate summary for build analysis
169
turbo run build --summarize
170

171
# Combine summary with profiling
172
turbo run build test lint --summarize --profile=full-analysis.json
173

174
# Summary with custom cache settings
175
turbo run build --cache=local:w,remote:r --summarize
176
```
177

178
### Daemon Performance
179

180
Control the Turbo daemon for improved performance through persistent processes.
181

182
```bash { .api }
183
# Daemon control options
184
--daemon                           # Force daemon usage
185
--no-daemon                        # Force disable daemon
186
# Default: automatic detection based on environment
187

188
# Daemon examples
189
turbo run build --daemon
190
turbo run build --no-daemon
191
```
192

193
**Usage Examples:**
194

195
```bash
196
# Force daemon usage for maximum performance
197
turbo run build --daemon
198

199
# Disable daemon for CI environments
200
turbo run build --no-daemon
201

202
# Let Turbo decide automatically (default)
203
turbo run build
204
```
205

206
## Performance Analysis Types
207

208
```typescript { .api }
209
interface CacheConfig {
210
  local: "r" | "w" | "rw";
211
  remote: "r" | "w" | "rw";
212
}
213

214
interface ProfileData {
215
  tasks: TaskProfile[];
216
  summary: ExecutionSummary;
217
  timing: TimingData;
218
}
219

220
interface TaskProfile {
221
  task: string;
222
  package: string;
223
  duration: number;
224
  cache_hit: boolean;
225
  cache_source: "local" | "remote" | null;
226
  dependencies: string[];
227
}
228

229
interface ExecutionSummary {
230
  total_time: number;
231
  cache_hit_rate: number;
232
  tasks_executed: number;
233
  tasks_cached: number;
234
  parallel_efficiency: number;
235
}
236

237
interface TimingData {
238
  start_time: string;
239
  end_time: string;
240
  task_timings: Record<string, number>;
241
  cache_timings: Record<string, number>;
242
}
243

244
interface GraphData {
245
  nodes: GraphNode[];
246
  edges: GraphEdge[];
247
  metadata: GraphMetadata;
248
}
249

250
interface GraphNode {
251
  id: string;
252
  label: string;
253
  package: string;
254
  type: "task" | "package";
255
  duration?: number;
256
  cache_hit?: boolean;
257
}
258

259
interface GraphEdge {
260
  from: string;
261
  to: string;
262
  type: "depends" | "triggers";
263
}
264

265
interface GraphMetadata {
266
  generated_at: string;
267
  turbo_version: string;
268
  total_tasks: number;
269
  format: "svg" | "png" | "json" | "html" | "mermaid" | "dot";
270
}
271
```