main.a3f7c9.js). When the file changes, the hash changes, making it a new URL that bypasses cache automatically. If a website isn't using cache busting properly, users may need to manually clear cache to see updates.
- The Problem Cache Busting Solves
- Method 1: Filename Versioning
- Method 2: Content Hashing (Recommended)
- Method 3: Query String Versioning
- Method 4: HTTP Cache Headers (ETag and Last-Modified)
- The Optimal Caching Strategy
- Why Users Still Sometimes Need to Clear Cache
- Service Worker Cache: The Persistent Layer
- Frequently Asked Questions
- The Problem Cache Busting Solves
- Method 1: Filename Versioning
- Method 2: Content Hashing (Recommended)
- Method 3: Query String Versioning
- Method 4: HTTP Cache Headers (ETag and Last-Modified)
- The Optimal Caching Strategy
- Why Users Still Sometimes Need to Clear Cache
- Service Worker Cache: The Persistent Layer
- Frequently Asked Questions
If you've ever deployed a website update and wondered why users still see the old version — or why you need to tell users to "clear their cache" after a release — the answer is that your caching strategy needs work. Cache busting is the systematic solution. This guide explains what cache busting is, the technical approaches, their tradeoffs, and when each is appropriate.
Stuck Seeing Old Site Content? Clear Your Cache Now
If a website hasn't implemented proper cache busting, you may need to manually clear your browser's cache to see the latest version. The Clear Cache extension handles this in one click.
Add to Chrome — FreeThe Problem Cache Busting Solves
Browser caching is intentional — it makes websites faster by storing files locally so they don't need to be re-downloaded on every visit. Browsers follow cache headers set by the server. If a server sets:
Cache-Control: max-age=31536000
...the browser will use the cached copy of that file for up to one year without re-checking the server.
This creates a problem when files change. Your HTML might reference the new styles.css, but users' browsers already have the old styles.css cached. The browser serves the old version, the layout looks broken, and your carefully deployed update looks like a regression.
The fundamental tension: you want static files cached aggressively (for performance), but you need users to get updates immediately when files change. Cache busting resolves this by making each version of a file have a unique URL.
Method 1: Filename Versioning
The simplest approach: include a version number in the filename itself.
styles.v1.css → styles.v2.css main.v1.0.js → main.v1.1.js
When you deploy an update, you change the filename and update the HTML reference. The browser has never seen this URL before, so it downloads it fresh regardless of cache settings.
Pros: Simple to implement manually, works for small sites, no build tool required
Cons: Manual — easy to forget to update, doesn't scale to many files, version numbers become meaningless without a changelog
Method 2: Content Hashing (Recommended)
Modern build tools (Webpack, Vite, Parcel) automatically generate a hash of each file's contents and include it in the filename:
styles.a3f7c9d2.css main.bundle.8e2f1a44.js
The hash is deterministic: the same file content always produces the same hash. When a file changes, its hash changes, making a new filename that the browser has never cached.
This allows long cache lifetimes (max-age=31536000 — one year) for hashed assets, since the URL itself changes whenever the content changes. The HTML file that references these assets has a short cache lifetime or no cache, ensuring it's always current.
Pros: Fully automatic when configured in build tools, no manual version tracking, works perfectly with CDNs, allows aggressive caching of static assets
Cons: Requires a build tool, doesn't work for files referenced outside the build system (like images in a CMS)
| Build Tool | Content Hashing Configuration |
|---|---|
| Webpack | output: { filename: '[name].[contenthash].js' } |
| Vite | Enabled by default in production builds |
| Parcel | Enabled by default in production mode |
| Rollup | output: { entryFileNames: '[name]-[hash].js' } |
| Gulp | Use gulp-rev plugin to append hashes |
Method 3: Query String Versioning
Append a version parameter to the file URL without changing the filename:
<link rel="stylesheet" href="styles.css?v=2.1.0"> <script src="main.js?v=2.1.0"></script>
The browser considers styles.css?v=1.0 and styles.css?v=2.0 as different URLs and downloads both.
Pros: Easy to implement (just update the version string), works without a build tool, preserves human-readable filenames
Cons: Some CDNs and proxy servers ignore query strings and treat the URL as the same resource regardless of parameters. This is a significant limitation — CDN caches may not bust properly, and users behind corporate proxies may still get old files even after you update the version parameter.
styles.css?v=1 and styles.css?v=2 return the same cached response. Use filename-based versioning for CDN-served assets to avoid this issue.
Method 4: HTTP Cache Headers (ETag and Last-Modified)
Rather than changing URLs, these methods use HTTP headers to let browsers check if a cached file is still current:
ETag (Entity Tag)
The server sends a unique identifier (hash) for the current version of a file:
ETag: "33a64df551425fcc55e4d42a148795d9f25f89d4"
On subsequent requests, the browser sends If-None-Match: "33a64df...". If the file hasn't changed, the server responds with 304 Not Modified and the browser uses its cached copy. If the file changed, the server sends the new version with a new ETag.
Last-Modified
The server sends the file's modification timestamp. On subsequent requests, the browser sends If-Modified-Since. Similar conditional request/response pattern to ETag.
Pros: Automatically handles any file changes without modifying URLs, transparent to both server and browser
Cons: Requires a network request to validate (even if the file hasn't changed), slower than content-hashed filenames for unchanged files
The Optimal Caching Strategy
Modern best practice combines aggressive caching with content hashing:
main.a3f7c9.js and styles.8e2f1a.css get Cache-Control: max-age=31536000, immutable. If the content changes, the hash changes and the filename changes — so the 1-year cache is never stale.
Cache-Control: no-cache or Cache-Control: max-age=0, must-revalidate for HTML. The HTML is always revalidated against the server, ensuring it references the latest hashed assets.
Why Users Still Sometimes Need to Clear Cache
Even with good cache busting, users occasionally need to clear cache manually. Common reasons:
- A bug in the cache busting configuration deployed incorrect hashes
- An old service worker serving cached responses that override HTTP cache
- The site was partially updated and old + new assets mixed in an incompatible way
- A CDN still serving stale content because its cache wasn't purged after deployment
- The user's browser cache is corrupted (rare but it happens)
Users: One Click to Clear Any Site's Cache
When a website update isn't showing through because of stale cache, the Clear Cache extension clears it instantly without clearing your other sites' data.
Install Clear Cache — FreeService Worker Cache: The Persistent Layer
Service workers introduce a cache layer that operates independently from standard browser HTTP cache — and which requires explicit application logic to update. If a site has a service worker with aggressive caching:
- Even clearing browser cache may not clear service worker cache
- The service worker itself must check for updates and decide whether to serve cached or network content
- A badly implemented service worker can cause users to see stale content indefinitely regardless of cache busting headers
Service worker cache clearing requires special steps: navigating to chrome://settings/content/all, finding the site, and clearing all stored data including service workers — or the developer implementing an update notification UI.
Frequently Asked Questions
What is cache busting?
Cache busting is a technique that forces browsers to download a new version of a file instead of using the cached version. It works by changing the file's URL when content changes — via a version number, content hash, or timestamp added to the filename or URL. When the URL changes, the browser treats it as a new resource and downloads it fresh.
What are the main cache busting methods?
The main methods: (1) File name versioning — include version in the filename (styles.v2.css), (2) Content hash — append a hash of file contents to the filename (styles.a3f7c9.css), (3) Query string — append a version parameter (?v=2.1), (4) ETag headers — server sends a unique identifier for conditional requests. Content hashing is the most reliable modern approach.
Why does cache busting matter for website updates?
Without cache busting, browsers keep using old cached CSS, JavaScript, and images after a site update. This causes broken layouts and JavaScript errors because old code runs against new HTML. Cache busting ensures every user's browser gets the version of each file that matches the current HTML structure.
Does adding ?v=timestamp to CSS files work for cache busting?
In most browsers yes, but some CDNs and proxies ignore query strings and cache the URL as if the parameter doesn't exist. For CDN-served assets, filename-based cache busting (changing the actual filename) is more reliable because different filenames are always treated as different resources.
When should a user clear cache vs a developer using cache busting?
Cache busting is what developers implement so users never need to clear cache manually. When properly implemented, all updates reach users automatically. User-side cache clearing is only needed when cache busting wasn't implemented, there's a caching bug, or a service worker is serving stale content. Frequent user requests to clear cache signal a developer problem to fix.
More Free Chrome Tools by Peak Productivity
