claudeguide-engineer 1.14.8

package/.claude/skills/web-frameworks/references/turborepo-caching.md

@@ -0,0 +1,551 @@
+# Turborepo Caching Strategies
+
+Local caching, remote caching, cache invalidation, and optimization techniques.
+
+## Local Caching
+
+### How It Works
+
+Turborepo caches task outputs based on inputs:
+
+1. **Hash inputs**: Source files, dependencies, environment variables, config
+2. **Run task**: If hash not in cache
+3. **Save outputs**: Store in `.turbo/cache`
+4. **Restore on match**: Instant completion on cache hit
+
+Default cache location: `./node_modules/.cache/turbo`
+
+### Cache Configuration
+
+```json
+// turbo.json
+{
+  "pipeline": {
+    "build": {
+      "outputs": ["dist/**", ".next/**", "!.next/cache/**"],
+      "cache": true  // default
+    },
+    "dev": {
+      "cache": false  // don't cache dev servers
+    }
+  }
+}
+```
+
+### Outputs Configuration
+
+Specify what gets cached:
+
+```json
+{
+  "build": {
+    "outputs": [
+      "dist/**",              // All files in dist
+      "build/**",             // Build directory
+      ".next/**",             // Next.js output
+      "!.next/cache/**",      // Exclude Next.js cache
+      "storybook-static/**",  // Storybook build
+      "*.tsbuildinfo"         // TypeScript build info
+    ]
+  }
+}
+```
+
+**Best practices:**
+- Include all build artifacts
+- Exclude nested caches
+- Include type definitions
+- Include generated files
+
+### Clear Local Cache
+
+```bash
+# Remove cache directory
+rm -rf ./node_modules/.cache/turbo
+
+# Or use turbo command with --force
+turbo run build --force
+
+# Clear and rebuild
+turbo run clean && turbo run build
+```
+
+## Remote Caching
+
+Share cache across team and CI/CD.
+
+### Vercel Remote Cache (Recommended)
+
+**Setup:**
+```bash
+# Login to Vercel
+turbo login
+
+# Link repository
+turbo link
+```
+
+**Use in CI:**
+```yaml
+# .github/workflows/ci.yml
+env:
+  TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
+  TURBO_TEAM: ${{ secrets.TURBO_TEAM }}
+
+steps:
+  - run: turbo run build test
+```
+
+Get tokens from Vercel dashboard:
+1. Go to https://vercel.com/account/tokens
+2. Create new token
+3. Add as GitHub secrets
+
+### Custom Remote Cache
+
+Configure custom remote cache server:
+
+```json
+// .turbo/config.json
+{
+  "teamid": "team_xxx",
+  "apiurl": "https://cache.example.com",
+  "token": "your-token"
+}
+```
+
+Or use environment variables:
+```bash
+export TURBO_API="https://cache.example.com"
+export TURBO_TOKEN="your-token"
+export TURBO_TEAM="team_xxx"
+```
+
+### Remote Cache Verification
+
+```bash
+# Check cache status
+turbo run build --output-logs=hash-only
+
+# Output shows:
+# • web:build: cache hit, replaying logs [hash]
+# • api:build: cache miss, executing [hash]
+```
+
+## Cache Signatures
+
+Cache invalidated when these change:
+
+### 1. Source Files
+
+All tracked Git files in package:
+```
+packages/ui/
+├── src/
+│   ├── button.tsx     # Tracked
+│   └── input.tsx      # Tracked
+├── dist/              # Ignored (in .gitignore)
+└── node_modules/      # Ignored
+```
+
+### 2. Package Dependencies
+
+Changes in package.json:
+```json
+{
+  "dependencies": {
+    "react": "18.2.0"  // Version change invalidates cache
+  }
+}
+```
+
+### 3. Environment Variables
+
+Configured in pipeline:
+```json
+{
+  "build": {
+    "env": ["NODE_ENV", "API_URL"]  // Changes invalidate cache
+  }
+}
+```
+
+### 4. Global Dependencies
+
+Files affecting all packages:
+```json
+{
+  "globalDependencies": [
+    "**/.env.*local",
+    "tsconfig.json",
+    ".eslintrc.js"
+  ]
+}
+```
+
+### 5. Task Configuration
+
+Changes to turbo.json pipeline:
+```json
+{
+  "build": {
+    "dependsOn": ["^build"],
+    "outputs": ["dist/**"]  // Config changes invalidate cache
+  }
+}
+```
+
+## Input Control
+
+### Override Input Detection
+
+Explicitly define what affects cache:
+
+```json
+{
+  "build": {
+    "inputs": [
+      "src/**/*.ts",           // Include TS files
+      "src/**/*.tsx",          // Include TSX files
+      "!src/**/*.test.ts",     // Exclude tests
+      "!src/**/*.stories.tsx", // Exclude stories
+      "package.json",          // Include package.json
+      "tsconfig.json"          // Include config
+    ]
+  }
+}
+```
+
+Use cases:
+- Exclude test files from build cache
+- Exclude documentation from production builds
+- Include only source files, not generated files
+
+### Global vs Package Inputs
+
+**Global inputs** (affect all packages):
+```json
+{
+  "globalDependencies": [".env", "tsconfig.json"]
+}
+```
+
+**Package inputs** (affect specific tasks):
+```json
+{
+  "pipeline": {
+    "build": {
+      "inputs": ["src/**"]
+    }
+  }
+}
+```
+
+## Environment Variables
+
+### Cached Environment Variables
+
+Include in cache signature:
+
+```json
+{
+  "pipeline": {
+    "build": {
+      "env": [
+        "NODE_ENV",           // Must match for cache hit
+        "NEXT_PUBLIC_API_URL",
+        "DATABASE_URL"
+      ]
+    }
+  }
+}
+```
+
+Cache invalidated when values change.
+
+### Pass-Through Environment Variables
+
+Don't affect cache:
+
+```json
+{
+  "pipeline": {
+    "build": {
+      "passThroughEnv": [
+        "DEBUG",        // Different values use same cache
+        "LOG_LEVEL",
+        "VERBOSE"
+      ]
+    }
+  }
+}
+```
+
+Use for: Debug flags, log levels, non-production settings
+
+### Global Environment Variables
+
+Available to all tasks:
+
+```json
+{
+  "globalEnv": [
+    "NODE_ENV",
+    "CI",
+    "VERCEL"
+  ]
+}
+```
+
+## Cache Optimization Strategies
+
+### 1. Granular Outputs
+
+Define precise outputs to minimize cache size:
+
+```json
+// ❌ Bad - caches too much
+{
+  "build": {
+    "outputs": ["**"]
+  }
+}
+
+// ✅ Good - specific outputs
+{
+  "build": {
+    "outputs": ["dist/**", "!dist/**/*.map"]
+  }
+}
+```
+
+### 2. Exclude Unnecessary Files
+
+```json
+{
+  "build": {
+    "outputs": [
+      ".next/**",
+      "!.next/cache/**",      // Exclude Next.js cache
+      "!.next/server/**/*.js.map",  // Exclude source maps
+      "!.next/static/**/*.map"
+    ]
+  }
+}
+```
+
+### 3. Separate Cacheable Tasks
+
+```json
+{
+  "pipeline": {
+    "build": {
+      "dependsOn": ["^build"],
+      "cache": true
+    },
+    "test": {
+      "dependsOn": ["build"],
+      "cache": true  // Separate from build
+    },
+    "dev": {
+      "cache": false  // Never cache
+    }
+  }
+}
+```
+
+### 4. Use Input Filters
+
+Only track relevant files:
+
+```json
+{
+  "build": {
+    "inputs": [
+      "src/**/*.{ts,tsx}",
+      "!src/**/*.{test,spec}.{ts,tsx}",
+      "public/**",
+      "package.json"
+    ]
+  }
+}
+```
+
+## Cache Analysis
+
+### Inspect Cache Hits/Misses
+
+```bash
+# Dry run with JSON output
+turbo run build --dry-run=json | jq '.tasks[] | {package: .package, task: .task, cache: .cache}'
+```
+
+### View Task Graph
+
+```bash
+# Generate task graph
+turbo run build --graph
+
+# Output: graph.html (open in browser)
+```
+
+### Cache Statistics
+
+```bash
+# Run with summary
+turbo run build --summarize
+
+# Output: .turbo/runs/[hash].json
+```
+
+## CI/CD Cache Configuration
+
+### GitHub Actions
+
+```yaml
+name: CI
+on: [push, pull_request]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 18
+
+      - name: Install dependencies
+        run: npm install
+
+      - name: Build and test
+        run: turbo run build test lint
+        env:
+          TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
+          TURBO_TEAM: ${{ secrets.TURBO_TEAM }}
+
+      # Optional: Cache node_modules
+      - uses: actions/cache@v3
+        with:
+          path: node_modules
+          key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
+```
+
+### GitLab CI
+
+```yaml
+image: node:18
+
+cache:
+  key: ${CI_COMMIT_REF_SLUG}
+  paths:
+    - node_modules/
+    - .turbo/
+
+build:
+  stage: build
+  script:
+    - npm install
+    - turbo run build test
+  variables:
+    TURBO_TOKEN: $TURBO_TOKEN
+    TURBO_TEAM: $TURBO_TEAM
+```
+
+## Troubleshooting
+
+### Cache Not Working
+
+**Check outputs are defined:**
+```bash
+turbo run build --dry-run=json | jq '.tasks[] | {task: .task, outputs: .outputs}'
+```
+
+**Verify cache location:**
+```bash
+ls -la ./node_modules/.cache/turbo
+```
+
+**Check environment variables:**
+```bash
+echo $TURBO_TOKEN
+echo $TURBO_TEAM
+```
+
+### Cache Too Large
+
+**Analyze cache size:**
+```bash
+du -sh ./node_modules/.cache/turbo
+```
+
+**Reduce outputs:**
+```json
+{
+  "build": {
+    "outputs": [
+      "dist/**",
+      "!dist/**/*.map",      // Exclude source maps
+      "!dist/**/*.test.js"   // Exclude test files
+    ]
+  }
+}
+```
+
+**Clear old cache:**
+```bash
+# Turborepo doesn't auto-clean, manually remove:
+rm -rf ./node_modules/.cache/turbo
+```
+
+### Remote Cache Connection Issues
+
+**Test connection:**
+```bash
+curl -I https://cache.example.com
+```
+
+**Verify token:**
+```bash
+turbo link
+# Should show: "Remote caching enabled"
+```
+
+**Check logs:**
+```bash
+turbo run build --output-logs=full
+```
+
+## Best Practices
+
+1. **Define precise outputs** - Only cache necessary files
+2. **Exclude nested caches** - Don't cache caches (.next/cache)
+3. **Use remote caching** - Share cache across team and CI
+4. **Track relevant inputs** - Use `inputs` to filter files
+5. **Separate env vars** - Use `passThroughEnv` for debug flags
+6. **Cache test results** - Include coverage in outputs
+7. **Don't cache dev servers** - Set `cache: false` for dev tasks
+8. **Use global dependencies** - Share config across packages
+9. **Monitor cache performance** - Use `--summarize` to analyze
+10. **Clear cache periodically** - Remove stale cache manually
+
+## Cache Performance Tips
+
+**For CI/CD:**
+- Enable remote caching
+- Run only changed packages: `--filter='...[origin/main]'`
+- Use `--continue` to see all errors
+- Cache node_modules separately
+
+**For Local Development:**
+- Keep local cache enabled
+- Don't force rebuild unless needed
+- Use filters to build only what changed
+- Clear cache if issues arise
+
+**For Large Monorepos:**
+- Use granular outputs
+- Implement input filters
+- Monitor cache size regularly
+- Consider cache size limits on remote cache