A practical cache-control checklist

Caching works best when the URL tells the truth about change. Classify the response, then choose a policy that matches its lifecycle.

Versioned static assets

When a filename contains a content hash, it can be cached for a long time because a changed file receives a new URL.

Cache-Control: public, max-age=31536000, immutable

HTML documents

Documents often keep the same URL while their contents change. Let caches store them, but require revalidation so a visitor does not remain on a stale release.

Cache-Control: public, max-age=0, must-revalidate
ETag: "revision-identifier"

Private responses

For personalised content, use private to prevent shared-cache reuse. For material that should not be stored at all, use no-store.

Verification checklist

• Inspect headers on cold and conditional requests.
• Confirm versioned URLs change when the bytes change.
• Check CDN and browser behaviour separately.
• Test that a rolled-back document still references existing assets.

← Back to all notes