Asset Versioning and Cache Busting: The Decisions That Matter
Adding version identifiers to asset filenames so browsers can cache them for a long time and still get updates.
Marcus Adeyemi
What is at stake
Without versioning, teams either serve stale files or lose caching entirely, and both hurt users.
The playbook
- Fingerprint CSS, JavaScript and images
- Serve versioned assets with long cache lifetimes
- Keep HTML cache lifetimes short
- Verify headers after deployment
- Purge CDN caches when needed
Where it goes wrong
Avoid:
- Query-string versioning on CDNs that ignore it
- Long cache times on HTML
- Manual version numbers
- Assets updated in place
The numbers behind it
| Measure | Figure |
|---|---|
| Fingerprints | content hashes in filenames change when files change |
| Immutable caching | versioned files can be cached for a year |
| HTML | should not be cached long, as it points to assets |
| Build tools | generate fingerprinted filenames automatically |
Getting outside help
When to hand it over: Bring in help when users see stale assets after releases.
Where this comes from
- MDN Web Docs — HTTP caching
- web.dev — Love your cache
The figures and practices above come from the sources listed.
Working on something like this?
We take on Performance & Accessibility work for teams who want it done once, properly. Tell us what you are building and we will tell you honestly whether we are the right studio for it. Start a project.
Where to go next
Spotted something wrong? Report an error on this page. We correct on the page and say what changed.
