@vodailoc/kilo-kit-mcp 1.1.0 → 1.2.0

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

@@ -1,551 +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
+# 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