Asset Caching Strategy

## The cache key is the URL Every HTTP cache — the browser's disk cache, a proxy, a CDN edge — stores a response under the URL that produced it. Nothing in that URL says which release the file came from or whether it is still correct. When a cache holds a copy it considers fresh, it serves it without contacting the server at all. That property is the whole prize. On a repeat visit, a fresh cached bundle costs zero requests, zero bytes, and zero latency; it is the cheapest performance win a frontend has. It is also what makes long caching frightening: once a browser holds a year-long copy of `/app.js`, there is no reliable way to reach out and tell it that copy is now wrong. Caches are one-way — you can hand a client something, you cannot take it back. So the discipline reduces to one rule: **never change the bytes behind a URL; change the URL.** ## Fingerprinting: hash the contents, not the release A build tool implements that rule by naming each output file after a hash of its own contents: ``` # release 12 assets/app.9f2c1a4b.js assets/vendor.4d81ee02.js assets/styles.aa71b3c0.css # release 13 — only application source changed assets/app.5e0b77d1.js <- new URL, nobody has this cached assets/vendor.4d81ee02.js <- identical bytes, identical URL, still cached assets/styles.aa71b3c0.css <- unchanged too ``` Two things follow. First, **correctness**: a changed file is unreachable at its old address, so no cache anywhere can serve the old version of the new file. There is no invalidation step to forget, no purge to get wrong, no user stuck on a stale copy. Second, **economy**: only what actually changed is re-fetched. The dependency bundle, the icon sprite, the stylesheet you did not touch all keep their addresses, and the returning user downloads only the delta. ## Why a release number in the name is worse `app.v13.js` also solves correctness — every release is a fresh URL. But it renames *everything* every time, so a typo fix in one component costs every returning visitor a full re-download of the whole asset set. The same objection applies to a global query-string bump like `app.js?v=13`: browsers do include the query string in the cache key, so it busts the cache, but it busts it for every asset at once, and it makes the URL's stability depend on a number that has nothing to do with the file. Content hashing gets you the invalidation you need and nothing more. ## The policy that follows Once filenames are content-addressed, the caching policy is almost mechanical, and it has two tiers: - **Hashed static assets** get the longest lifetime you are willing to write — conventionally a year of `max-age`, commonly paired with `immutable`. The URL is a promise that these bytes will never change. - **The HTML document** gets a short lifetime or is revalidated on every navigation. It is the one address that must stay stable (users type it, link to it, bookmark it), so it cannot be fingerprinted, and it is the thing that carries the new asset names. The document is the invalidation point of the entire system. That asymmetry is the design. Everything expensive is immutable and cached forever; the one small, cheap file is uncached and re-fetched, and it redirects the browser to whatever the current build is. ## Hashes compose, deepest first Hashing is applied bottom-up because references travel upward. Swap a font file and its URL changes; the stylesheet that references that URL therefore has different bytes, so the stylesheet's hash changes; the document that references the stylesheet now names a different file. A single leaf change ripples up exactly one chain and leaves every unrelated file untouched. This is also why a build's asset graph has to be hashed in dependency order — you cannot know a parent's hash until every child's final URL is fixed. ## What hashing does not solve - **First visits.** A cold visitor downloads everything regardless; fingerprinting is a repeat-visit optimization. - **HTML freshness.** Hashed assets are safe, but if the document is over-cached, clients keep pointing at an old build long after deploy. - **Old files disappearing.** Because a client can hold an old document, the previous build's files must remain fetchable for a while after a deploy — deleting them is what turns "safe caching" into a post-deploy 404. - **Chunks that churn for no reason.** A hash only buys you stability if the bytes are actually stable between builds; embedded build metadata or renumbered internal identifiers can change a file that is semantically unchanged, silently costing every returning user a re-download.