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/