Audit Cache Headers
Cache headers decide whether a returning visitor waits on the network at all. A missing immutable on a hashed asset costs every repeat visit a revalidation round trip.
Procedure
Dump the headers for a hashed asset and for the HTML entry point:
curl -sI https://shop.example.com/assets/app.9f2c1a.js | grep -iE 'cache-control|etag|last-modified|vary' curl -sI https://shop.example.com/ | grep -iE 'cache-control|etag|vary'For content-addressed files, the target is
Cache-Control: public, max-age=31536000, immutable. The filename hash is the cache key; the URL changes when the bytes change.For HTML, the target is
Cache-Control: no-cache(revalidate, do not store blindly) so a deploy is visible on the next navigation.Confirm a validator exists when the URL is not hashed: a stable
ETaglets a 304 replace the body transfer.Check
Varyon negotiated responses —Vary: Accept-Encodingat minimum, plusVary: Acceptwhen you serve AVIF/WebP by content negotiation.Verify the CDN does not strip or rewrite your origin header:
curl -sI https://cdn.shop.example.com/app.9f2c1a.js | grep -i 'x-cache\|age\|cache-control'Walk the deploy path: after a release, an old hashed URL should still 200 from cache, and the new HTML must reference the new hash.
Pitfalls
- Setting
max-age=31536000on a filename that does not contain a hash; the fix for a bug can never reach the client. - Caching HTML for a year, so users see the previous deploy until they hard-refresh.
Cache-Control: no-storeon assets that never change; every visit refetches them.- Trusting
ETagvalues that change on every request (some servers emit a timestamp-based tag), which disables 304s entirely. - Forgetting
immutable, so browsers still issue a conditional request on reload within the max-age window.
Verification
curl -sI https://shop.example.com/assets/app.9f2c1a.js | grep -i cache-control
The asset must return max-age=31536000, immutable; the HTML must return no-cache. Report both header lines and the URL each came from.