What is Cache Busting?

Cache busting publishes changed content under a new URL, usually by putting a content hash or version identifier in the file name, path, or query string. HTTP caches look up stored responses by URL, so a request for the new address cannot be answered with the copy stored under the old one, as long as no cache is configured to ignore the part of the URL that changed.

An HTTP cache reuses a stored response while it is fresh without contacting the origin, so a file served with a long max-age stops generating the requests through which the server could replace it. A CDN can usually be purged, but a purge does not reach copies that browsers already hold. Cache busting sidesteps both problems. By specification a cache key contains at least the request method and the URL; some CDNs can be configured to leave the query string out of it. A URL whose key has not been stored has no stored response, so each cache has to forward the request toward the origin. In practice the versioned files get a long max-age (MDN’s example uses one year, max-age=31536000), optionally with immutable, while the document that references them is served with no-cache, so that a cache must revalidate it before reusing it and a new page load receives the current file names. MDN notes that no-cache does not guarantee revalidation for history navigation, so the Back button can restore an earlier page. Bundlers such as webpack and Vite generate the hashed file names at build time.

File name or query string? Both app.3f9a1c.js and app.js?v=3f9a1c change the URL, but a query-string version only works if every cache on the path keeps the query string in its cache key. Cloudflare’s default Standard caching level does, while its Ignore Query String level serves one cached copy of a static file whatever the query value. Amazon CloudFront caches by query string only when the distribution is configured to, and Google Cloud CDN backend buckets need the version parameter on an include list. A query-string version also tends to leave one file at the origin that each release overwrites in place, so a page from the previous release that requests its old ?v= URL after a cache miss receives the new release’s file. Google’s Cloud CDN guidance recommends unique file names instead, because a file updated in place can be cached while incomplete.
Will unchanged files keep their URL across releases? With a content hash they do, provided the build emits identical bytes; a release number or timestamp applied to every path changes every URL at each release and discards cached copies of files that did not change. A hash can still change for a file whose source did not: webpack’s caching guide shows a vendor bundle’s [contenthash] changing after an unrelated module was added, because module IDs followed resolution order. The guide notes that webpack 5’s production mode defaults to deterministic module IDs, and it also moves the runtime into its own chunk.
What order should a deploy follow? Upload the new versioned files first and publish the document that references them last; Google’s Cloud CDN guidance calls uploading dependencies before the files that reference them crucial. Keep the previous release’s files available as well: a page loaded before the deploy still requests the old names, and both webpack and Vite document failed chunk loads or import errors when a deploy deletes them. The webpack guide suggests letting the CDN expire old files after a day or so rather than at the next deploy, and reloading the page at most once when a chunk still fails to load, since a tab can stay open longer than the retention window.
What does immutable add to a long max-age? It tells clients not to revalidate the file on reload while it is still fresh, which saves conditional requests that would only return 304. It does not extend the lifetime, and it is only correct when the file at that URL will not change while the response is fresh, as with a hashed file name that is never overwritten. MDN notes that Chrome does not implement the directive and instead skips revalidating subresources on reload.

Use cache busting for subresources such as scripts, stylesheets, and images that browsers and CDNs should keep for a long time yet pick up right after a release. It cannot be applied to a URL that must stay the same, such as the HTML document that references those files; serve that document with no-cache so that browsers revalidate it on each new page load. If the CDN is set up to serve the document from its own cache without revalidating, purge that copy at each deploy as well; a purge alone does not update browsers. Every new cache key starts cold: each cache has to fetch the file once, from the origin or from a cache closer to the origin, before it can serve it.

Transloadit’s Smart CDN gives every transformed variant its own URL: the Workspace, the Template name, the source file path, and the transformation parameters are all part of the tlcdn.com address. Requesting a different size or format therefore changes the URL and produces a separate cached rendition, while a cache hit for the same URL reuses the cached result instead of running the Template again. For signed URLs, the effective cache lifetime of a response is bounded by the remaining signature lifetime.

The pages linked here do not describe a purge operation or what happens to a cached result when the original is replaced under an unchanged file path. Storing a replacement original under a new path changes the Smart CDN URL; test the unchanged-path case on your own Workspace before relying on it.

Explore Transloadit’s delivery capabilities

What is Cache Busting?

How Cache Busting works

Key facts

When Cache Busting matters

How Transloadit helps with Cache Busting

Sources

Turn media knowledge into a working pipeline