When hosting static assets behind a CDN, how do Cache-Control headers and versioned (content-hashed) URLs work together to let you cache aggressively while still rolling out updates safely?

## What Cache-Control tells the chain `Cache-Control` is an HTTP response header that tells every cache in the chain — the browser's local cache, any CDN edge PoP, and intermediate proxies — how to treat a given response. The relevant directives for static hosting are: | Directive | What it does | |---|---| | `max-age` | how many seconds a cache may serve the response without revalidating | | `s-maxage` | the same but specifically for shared/CDN caches, letting you set a different TTL for the CDN than for browsers | | `no-cache` | must revalidate with origin before reuse | | `no-store` | never cache at all | | `immutable` | tells the browser the resource will never change for the lifetime given, so it won't even issue a conditional revalidation request on things like reload | Origin attaches these headers to each file, and the CDN honors them when deciding how long to keep its edge copy before treating it as stale. ## The deployment problem The problem this alone doesn't solve is deployment: if a file is served at a fixed URL like `/app.js` and you set a one-year `max-age` on it, then ship a bug fix, every cache holding the old copy will keep serving the buggy version for up to a year. Shortening the TTL doesn't really fix this either; it just trades staleness risk for cache-effectiveness (constant revalidation traffic to origin, undermining the whole point of the CDN). **The actual solution is to change the URL whenever the content changes.** Build tooling (webpack, Vite, esbuild) computes a content hash of each output file and bakes it into the filename — `app.3f2a1c9.js` — so any change to the file's bytes produces a different filename. Because that URL is now permanently tied to one specific, immutable set of bytes, it becomes safe, even correct, to cache it as aggressively as possible with a long, `immutable` `Cache-Control`. There is no scenario in which that URL's content changes, so there's no staleness risk to guard against. ## The one file that can't follow the rule That leaves one file that can't follow this rule: whatever document references the hashed filenames, typically `index.html` or a generated asset manifest. That file's content must change on every deploy, so it's given `no-cache` (always revalidate) or a very short `max-age`, ensuring browsers and edge caches check back on every load or near-every load. This produces a clean split: - a small, cheap-to-revalidate **entry point** that's always fresh, - fronting a large body of **hashed assets** that can be cached essentially forever. The trade-off is entirely in that split — you're accepting slightly slower delivery of one small file in exchange for maximal, risk-free caching of everything else, which for a typical app is 95%+ of total byte volume. ## Failure modes Failure modes cluster around getting this split wrong. - **A team forgets to hash a frequently-changing asset** (e.g. a logo file with a fixed name but aggressive `max-age`): updates to it simply won't show up for users with a warm cache until the TTL lapses — a classic 'why isn't my change showing up' bug that's often mistakenly fixed by manually purging the CDN rather than fixing the caching strategy. - **Conversely, the entry HTML is accidentally cached long-term** (e.g. a misconfigured CDN rule that overrides origin-set `Cache-Control`): users can get stuck on an old version indefinitely, referencing hashed asset URLs that may have been cleaned up from storage, producing 404s on chunk loads. Another subtlety is that `s-maxage` and `max-age` diverging is intentional and useful — you might want a CDN to hold a copy for a week while browsers only trust their local copy for an hour, so a CDN-level purge propagates to end users faster than waiting out browser cache lifetimes, since the CDN is the layer you control directly. ## Where it shows up A concrete real-world instance of this is any modern SPA/JAMstack deployment pipeline — e.g. a Next.js or Vite build publishing hashed static asset output to a CDN with a one-year `immutable` `Cache-Control`, while the HTML shell or a manifest file is served with `no-cache`, so each deploy is visible to users essentially immediately without any purge step being required at all.