Without documented cache-busting strategy, every developer on the team is guessing: does the CDN auto-purge on deploy? Do users need to hard-refresh to get the latest build? Are the service worker caches versioned? ISO 25010:2011 time-behaviour requires that the system delivers correct and current assets; gaps in cache-busting understanding lead to incidents where users receive stale JavaScript after a critical bug fix, because no one was certain which caching layer was holding the old version.
Info because undocumented caching is a knowledge-management gap rather than an active bug — the system may function correctly, but the absence of documentation increases incident response time when stale-asset problems do occur.
Document your caching stack in docs/caching-strategy.md or the project README. Cover three layers: asset filename hashing, HTTP cache headers, and service worker versioning.
<!-- docs/caching-strategy.md -->
## Cache Busting Strategy
### 1. Asset Hashing
All JS/CSS assets in `.next/static/` are named with content hashes (e.g., `main-abc123.js`).
Filenames change only when file content changes.
### 2. HTTP Headers
- Hashed assets: `Cache-Control: public, immutable, max-age=31536000`
- HTML: `Cache-Control: public, no-cache`
### 3. Service Worker
Cache name includes app version (`app-cache-v2.1.0`).
Old caches are deleted in the `activate` event.
ID: performance-deep-dive.regression-prevention.cache-busting-documented
Severity: info
What to look for: Count all cache-related config files and documentation. Enumerate the cache invalidation strategy: content hashing, service worker versioning, CDN purge. Look for documentation on how cache invalidation works when deploying. Check whether HTML or service worker invalidates old caches. Look at build process for content-hash naming.
Pass criteria: Cache busting strategy is documented in README or deployment guide. Explains how assets are hashed, how old caches are invalidated, and how users get new versions on deploy. At least 1 documented cache-busting strategy in project docs or README.
Fail criteria: No cache busting strategy documented. Unclear how users get new versions after deploy.
Skip (N/A) when: Never — every project should document its caching strategy.
Cross-reference: For asset hashing, see asset-content-hash. For service worker versioning, see service-worker-cache-versioning.
Detail on fail: "No documentation on cache busting — developers unclear about how asset updates are deployed" or "Cache strategy relies on manual CDN purge (error-prone)"
Remediation: Document your caching strategy in README or deployment guide.
<!-- docs/caching-strategy.md -->
## Cache Busting
- Assets: content hash in filename (app.[hash].js)
- HTML: Cache-Control: no-cache