Turborepo Caching

1---
2name: turborepo-caching
3description: Configure Turborepo for efficient monorepo builds with local and remote caching. Use when setting up Turborepo, optimizing build pipelines, or implementing distributed caching.
4---
5 
6# Turborepo Caching
7 
8Production patterns for Turborepo build optimization.
9 
10## Do not use this skill when
11 
12- The task is unrelated to turborepo caching
13- You need a different domain or tool outside this scope
14 
15## Instructions
16 
17- Clarify goals, constraints, and required inputs.
18- Apply relevant best practices and validate outcomes.
19- Provide actionable steps and verification.
20- If detailed examples are required, open `resources/implementation-playbook.md`.
21 
22## Use this skill when
23 
24- Setting up new Turborepo projects
25- Configuring build pipelines
26- Implementing remote caching
27- Optimizing CI/CD performance
28- Migrating from other monorepo tools
29- Debugging cache misses
30 
31## Core Concepts
32 
33### 1. Turborepo Architecture
34 
35```
36Workspace Root/
37├── apps/
38│   ├── web/
39│   │   └── package.json
40│   └── docs/
41│       └── package.json
42├── packages/
43│   ├── ui/
44│   │   └── package.json
45│   └── config/
46│       └── package.json
47├── turbo.json
48└── package.json
49```
50 
51### 2. Pipeline Concepts
52 
53| Concept | Description |
54|---------|-------------|
55| **dependsOn** | Tasks that must complete first |
56| **cache** | Whether to cache outputs |
57| **outputs** | Files to cache |
58| **inputs** | Files that affect cache key |
59| **persistent** | Long-running tasks (dev servers) |
60 
61## Templates
62 
63### Template 1: turbo.json Configuration
64 
65```json
66{
67  "$schema": "https://turbo.build/schema.json",
68  "globalDependencies": [
69    ".env",
70    ".env.local"
71  ],
72  "globalEnv": [
73    "NODE_ENV",
74    "VERCEL_URL"
75  ],
76  "pipeline": {
77    "build": {
78      "dependsOn": ["^build"],
79      "outputs": [
80        "dist/**",
81        ".next/**",
82        "!.next/cache/**"
83      ],
84      "env": [
85        "API_URL",
86        "NEXT_PUBLIC_*"
87      ]
88    },
89    "test": {
90      "dependsOn": ["build"],
91      "outputs": ["coverage/**"],
92      "inputs": [
93        "src/**/*.tsx",
94        "src/**/*.ts",
95        "test/**/*.ts"
96      ]
97    },
98    "lint": {
99      "outputs": [],
100      "cache": true
101    },
102    "typecheck": {
103      "dependsOn": ["^build"],
104      "outputs": []
105    },
106    "dev": {
107      "cache": false,
108      "persistent": true
109    },
110    "clean": {
111      "cache": false
112    }
113  }
114}
115```
116 
117### Template 2: Package-Specific Pipeline
118 
119```json
120// apps/web/turbo.json
121{
122  "$schema": "https://turbo.build/schema.json",
123  "extends": ["//"],
124  "pipeline": {
125    "build": {
126      "outputs": [".next/**", "!.next/cache/**"],
127      "env": [
128        "NEXT_PUBLIC_API_URL",
129        "NEXT_PUBLIC_ANALYTICS_ID"
130      ]
131    },
132    "test": {
133      "outputs": ["coverage/**"],
134      "inputs": [
135        "src/**",
136        "tests/**",
137        "jest.config.js"
138      ]
139    }
140  }
141}
142```
143 
144### Template 3: Remote Caching with Vercel
145 
146```bash
147# Login to Vercel
148npx turbo login
149 
150# Link to Vercel project
151npx turbo link
152 
153# Run with remote cache
154turbo build --remote-only
155 
156# CI environment variables
157TURBO_TOKEN=your-token
158TURBO_TEAM=your-team
159```
160 
161```yaml
162# .github/workflows/ci.yml
163name: CI
164 
165on:
166  push:
167    branches: [main]
168  pull_request:
169 
170env:
171  TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
172  TURBO_TEAM: ${{ vars.TURBO_TEAM }}
173 
174jobs:
175  build:
176    runs-on: ubuntu-latest
177    steps:
178      - uses: actions/checkout@v4
179 
180      - uses: actions/setup-node@v4
181        with:
182          node-version: 20
183          cache: 'npm'
184 
185      - name: Install dependencies
186        run: npm ci
187 
188      - name: Build
189        run: npx turbo build --filter='...[origin/main]'
190 
191      - name: Test
192        run: npx turbo test --filter='...[origin/main]'
193```
194 
195### Template 4: Self-Hosted Remote Cache
196 
197```typescript
198// Custom remote cache server (Express)
199import express from 'express';
200import { createReadStream, createWriteStream } from 'fs';
201import { mkdir } from 'fs/promises';
202import { join } from 'path';
203 
204const app = express();
205const CACHE_DIR = './cache';
206 
207// Get artifact
208app.get('/v8/artifacts/:hash', async (req, res) => {
209  const { hash } = req.params;
210  const team = req.query.teamId || 'default';
211  const filePath = join(CACHE_DIR, team, hash);
212 
213  try {
214    const stream = createReadStream(filePath);
215    stream.pipe(res);
216  } catch {
217    res.status(404).send('Not found');
218  }
219});
220 
221// Put artifact
222app.put('/v8/artifacts/:hash', async (req, res) => {
223  const { hash } = req.params;
224  const team = req.query.teamId || 'default';
225  const dir = join(CACHE_DIR, team);
226  const filePath = join(dir, hash);
227 
228  await mkdir(dir, { recursive: true });
229 
230  const stream = createWriteStream(filePath);
231  req.pipe(stream);
232 
233  stream.on('finish', () => {
234    res.json({ urls: [`${req.protocol}://${req.get('host')}/v8/artifacts/${hash}`] });
235  });
236});
237 
238// Check artifact exists
239app.head('/v8/artifacts/:hash', async (req, res) => {
240  const { hash } = req.params;
241  const team = req.query.teamId || 'default';
242  const filePath = join(CACHE_DIR, team, hash);
243 
244  try {
245    await fs.access(filePath);
246    res.status(200).end();
247  } catch {
248    res.status(404).end();
249  }
250});
251 
252app.listen(3000);
253```
254 
255```json
256// turbo.json for self-hosted cache
257{
258  "remoteCache": {
259    "signature": false
260  }
261}
262```
263 
264```bash
265# Use self-hosted cache
266turbo build --api="http://localhost:3000" --token="my-token" --team="my-team"
267```
268 
269### Template 5: Filtering and Scoping
270 
271```bash
272# Build specific package
273turbo build --filter=@myorg/web
274 
275# Build package and its dependencies
276turbo build --filter=@myorg/web...
277 
278# Build package and its dependents
279turbo build --filter=...@myorg/ui
280 
281# Build changed packages since main
282turbo build --filter='...[origin/main]'
283 
284# Build packages in directory
285turbo build --filter='./apps/*'
286 
287# Combine filters
288turbo build --filter=@myorg/web --filter=@myorg/docs
289 
290# Exclude package
291turbo build --filter='!@myorg/docs'
292 
293# Include dependencies of changed
294turbo build --filter='...[HEAD^1]...'
295```
296 
297### Template 6: Advanced Pipeline Configuration
298 
299```json
300{
301  "$schema": "https://turbo.build/schema.json",
302  "pipeline": {
303    "build": {
304      "dependsOn": ["^build"],
305      "outputs": ["dist/**"],
306      "inputs": [
307        "$TURBO_DEFAULT$",
308        "!**/*.md",
309        "!**/*.test.*"
310      ]
311    },
312    "test": {
313      "dependsOn": ["^build"],
314      "outputs": ["coverage/**"],
315      "inputs": [
316        "src/**",
317        "tests/**",
318        "*.config.*"
319      ],
320      "env": ["CI", "NODE_ENV"]
321    },
322    "test:e2e": {
323      "dependsOn": ["build"],
324      "outputs": [],
325      "cache": false
326    },
327    "deploy": {
328      "dependsOn": ["build", "test", "lint"],
329      "outputs": [],
330      "cache": false
331    },
332    "db:generate": {
333      "cache": false
334    },
335    "db:push": {
336      "cache": false,
337      "dependsOn": ["db:generate"]
338    },
339    "@myorg/web#build": {
340      "dependsOn": ["^build", "@myorg/db#db:generate"],
341      "outputs": [".next/**"],
342      "env": ["NEXT_PUBLIC_*"]
343    }
344  }
345}
346```
347 
348### Template 7: Root package.json Setup
349 
350```json
351{
352  "name": "my-turborepo",
353  "private": true,
354  "workspaces": [
355    "apps/*",
356    "packages/*"
357  ],
358  "scripts": {
359    "build": "turbo build",
360    "dev": "turbo dev",
361    "lint": "turbo lint",
362    "test": "turbo test",
363    "clean": "turbo clean && rm -rf node_modules",
364    "format": "prettier --write \"**/*.{ts,tsx,md}\"",
365    "changeset": "changeset",
366    "version-packages": "changeset version",
367    "release": "turbo build --filter=./packages/* && changeset publish"
368  },
369  "devDependencies": {
370    "turbo": "^1.10.0",
371    "prettier": "^3.0.0",
372    "@changesets/cli": "^2.26.0"
373  },
374  "packageManager": "npm@10.0.0"
375}
376```
377 
378## Debugging Cache
379 
380```bash
381# Dry run to see what would run
382turbo build --dry-run
383 
384# Verbose output with hashes
385turbo build --verbosity=2
386 
387# Show task graph
388turbo build --graph
389 
390# Force no cache
391turbo build --force
392 
393# Show cache status
394turbo build --summarize
395 
396# Debug specific task
397TURBO_LOG_VERBOSITY=debug turbo build --filter=@myorg/web
398```
399 
400## Best Practices
401 
402### Do's
403- **Define explicit inputs** - Avoid cache invalidation
404- **Use workspace protocol** - `"@myorg/ui": "workspace:*"`
405- **Enable remote caching** - Share across CI and local
406- **Filter in CI** - Build only affected packages
407- **Cache build outputs** - Not source files
408 
409### Don'ts
410- **Don't cache dev servers** - Use `persistent: true`
411- **Don't include secrets in env** - Use runtime env vars
412- **Don't ignore dependsOn** - Causes race conditions
413- **Don't over-filter** - May miss dependencies
414 
415## Resources
416 
417- [Turborepo Documentation](https://turbo.build/repo/docs)
418- [Caching Guide](https://turbo.build/repo/docs/core-concepts/caching)
419- [Remote Caching](https://turbo.build/repo/docs/core-concepts/remote-caching)
420