laurigates/configure-cache-busting

When to Use This Skill

| Use this skill when... | Use another approach when... | |------------------------|------------------------------| | Configuring content hashing for Next.js or Vite builds | Optimizing server-side caching (nginx, CDN config directly) | | Setting up CDN cache headers for Vercel or Cloudflare | Debugging build output issues (system-debugging agent) | | Verifying cache-busting compliance after a framework upgrade | Configuring general CI/CD workflows (/configure:workflows) | | Adding build verification scripts for hashed assets | Setting up container builds (/configure:container) | | Auditing static asset caching strategy across a project | Profiling frontend performance (browser devtools) |

Context

• Project root: !pwd
• Package files: !find . -maxdepth 1 -name 'package.json'
• Next.js config: !find . -maxdepth 1 -name 'next.config.*'
• Vite config: !find . -maxdepth 1 -name 'vite.config.*'
• Build output: !find . -maxdepth 1 -type d \( -name '.next' -o -name 'dist' -o -name 'out' \)
• CDN config: !find . -maxdepth 2 \( -path './vercel.json' -o -path './_headers' -o -path './_redirects' -o -path './public/_headers' \)
• Project standards: !find . -maxdepth 1 -name '.project-standards.yaml'

Parameters

Parse from command arguments:

• --check-only: Report compliance status without modifications (CI/CD mode)
• --fix: Apply fixes automatically without prompting
• --framework <nextjs|vite>: Override framework detection
• --cdn <cloudflare|vercel|none>: Specify CDN provider for cache header configuration

Execution

Execute this cache-busting configuration check:

Step 1: Detect project framework

Identify the framework from file structure:

| Indicator | Framework | Config File | |-----------|-----------|-------------| | next.config.js or next.config.mjs | Next.js | next.config.* | | next.config.ts | Next.js | next.config.ts | | vite.config.js or vite.config.ts | Vite | vite.config.* | | .next/ directory | Next.js (built) | Detection only | | dist/ directory + vite in package.json | Vite (built) | Detection only |

Check package.json dependencies for "next" or "vite".

If both detected, prompt user to specify with --framework. If neither detected, report unsupported and exit.

Step 2: Analyze current cache-busting state

For the detected framework, read config files and check:

Next.js - Read next.config.js/ts and check:

• [ ] generateBuildId configured for deterministic builds
• [ ] assetPrefix configured for CDN
• [ ] compress: true enabled
• [ ] poweredByHeader: false for security
• [ ] generateEtags configured
• [ ] Cache headers configured in headers() function

Vite - Read vite.config.js/ts and check:

• [ ] build.rollupOptions.output.entryFileNames uses [hash]
• [ ] build.rollupOptions.output.chunkFileNames uses [hash]
• [ ] build.rollupOptions.output.assetFileNames uses [hash]
• [ ] build.manifest: true for SSR/manifest-based routing
• [ ] build.cssCodeSplit configured appropriately

Step 3: Detect CDN provider

Identify CDN from project files:

| Indicator | CDN Provider | |-----------|--------------| | vercel.json exists | Vercel | | .vercelignore exists | Vercel | | _headers in root or public/ | Cloudflare Pages | | _redirects exists | Cloudflare Pages / Netlify | | wrangler.toml exists | Cloudflare Workers/Pages | | None of the above | Generic / None |

Step 4: Generate compliance report

Print a formatted compliance report:

Cache-Busting Compliance Report
================================
Project: [name]
Framework: [Next.js 14.x | Vite 5.x]
CDN Provider: [Vercel | Cloudflare | None detected]

Framework Configuration:
  Config file             next.config.js              [EXISTS | MISSING]
  Asset hashing           [hash] in filenames         [ENABLED | DISABLED]
  Build manifest          manifest files              [GENERATED | MISSING]
  Deterministic builds    Build ID configured         [PASS | NOT SET]
  Compression             gzip/brotli enabled         [PASS | DISABLED]

Cache Headers:
  Static assets           immutable, 1y               [CONFIGURED | MISSING]
  HTML files              no-cache, must-revalidate   [CONFIGURED | MISSING]
  API routes              varies by route             [CONFIGURED | N/A]
  CDN configuration       vercel.json/_headers        [EXISTS | MISSING]

Build Output (if built):
  Hashed filenames        app.[hash].js               [DETECTED | NOT BUILT]
  Content addressing      Unique hashes per version   [PASS | DUPLICATE]
  Manifest integrity      Valid manifest.json         [PASS | INVALID]

Overall: [X issues found]

Recommendations:
  [List specific fixes needed]

If --check-only, stop here.

Step 5: Apply configuration (if --fix or user confirms)

Based on detected framework, create or update config files using templates from REFERENCE.md:

1. Next.js: Update next.config.js/ts with deterministic builds, compression, cache headers
2. Vite: Update vite.config.js/ts with content hashing, manifest, chunk splitting

Step 6: Configure CDN cache headers

Based on detected CDN provider, create or update cache header configuration using templates from REFERENCE.md:

• Vercel: Create/update vercel.json with header rules
• Cloudflare Pages: Create public/_headers with cache rules
• Generic: Provide nginx configuration reference

Step 7: Add build verification

Create scripts/verify-cache-busting.js to verify content hashing works after build. Add package.json scripts for build verification. Use the verification script template from REFERENCE.md.

Step 8: Configure CI/CD verification

Add cache-busting verification step to GitHub Actions workflow. Use the CI workflow template from REFERENCE.md.

Step 9: Update standards tracking

Update .project-standards.yaml:

standards_version: "2025.1"
last_configured: "[timestamp]"
components:
  cache-busting: "2025.1"
  cache-busting-framework: "[nextjs|vite]"
  cache-busting-cdn: "[vercel|cloudflare|none]"
  cache-busting-verified: true

Step 10: Print final report

Print a summary of changes applied, cache strategy overview, and next steps for verification.

For detailed configuration templates and code examples, see REFERENCE.md.

Agentic Optimizations

| Context | Command | |---------|---------| | Quick compliance check | /configure:cache-busting --check-only | | Auto-fix all issues | /configure:cache-busting --fix | | Next.js project only | /configure:cache-busting --fix --framework nextjs | | Vite project only | /configure:cache-busting --fix --framework vite | | Cloudflare CDN headers | /configure:cache-busting --fix --cdn cloudflare | | Vercel CDN headers | /configure:cache-busting --fix --cdn vercel |

Output

Provide:

1. Compliance report with framework and CDN configuration status
2. List of changes made (if --fix) or proposed (if interactive)
3. Verification instructions and commands
4. CDN cache header examples
5. Next steps for deployment and monitoring

See Also

• /configure:all - Run all compliance checks
• /configure:status - Quick compliance overview
• /configure:workflows - GitHub Actions workflow standards
• /configure:dockerfile - Container configuration with build caching
• Next.js Documentation - https://nextjs.org/docs/pages/api-reference/next-config-js
• Vite Documentation - https://vitejs.dev/config/build-options.html
• Web.dev Caching Guide - https://web.dev/http-cache/