HTTP Caching for the Front End

The Cache-Control directives you will actually use

These are response directives. The "Defined in" column matters, because they do not all come from one document.

no-cache versus no-store is the classic trap. Use no-cache for content that must always be checked but is cheap to serve (HTML); use no-store when nothing may be kept. RFC 9111 warns that no-store is not a reliable privacy mechanism, since a misbehaving cache might ignore it. Protect secrets with access control, not a header.

The extensions come from different places. RFC 5861 is an Informational document, which RFC 9111 section 4.2.4 names as an example of extensions permitting stale responses; immutable is in RFC 8246, a Standards Track document. Support varies: web.dev reported stale-while-revalidate in Chrome 75 and Firefox 68 as of July 2019 and said a browser without support ignores it and falls back to max-age; support in other browsers today is not confirmed here. Check the MDN compatibility tables and your CDN's documentation. MDN also says stale-if-error as a request directive is not supported by any browser.

An illustrative header set for the product API:

Cache-Control: public, max-age=60, s-maxage=300, stale-while-revalidate=60
ETag: "v7"

Browsers and shared caches may store it; a browser treats it as fresh for 60 seconds, a CDN for 300; after that either may serve the old copy for up to 60 more seconds while revalidating.

Browser cache versus shared cache

The last row is the design fact. You can fix a bad CDN entry in minutes; a bad browser entry stays until it expires or the user clears it. Long browser lifetimes are safe only when the URL changes whenever the content does. A cookie alone does not make a response private (MDN), so personalised responses need an explicit private or no-store.

Vary: one URL, several responses

When one URL returns different bodies depending on a request header (language, compression), the Vary response header lists those headers. A cache must not reuse a stored response unless they match the original request's (RFC 9111 section 4.1); Vary: * never matches. MDN warns that varying on User-Agent drastically cuts reuse, and recommends Cache-Control: private rather than a cookie in Vary for personalised content.

The standard strategy: fingerprinted assets, revalidated HTML

You want the bundle cached as long as possible, but you also want a fix to reach every shopper at once. One URL cannot be both "cache forever" and "changes today".

The answer is to stop reusing URLs. Put a content hash (a short digest of the file's bytes) in the file name, called fingerprinting or cache busting. When the file changes its name changes, so to every cache it is a new resource.

// webpack.config.js (excerpt): the file name includes a hash of the content
module.exports = {
  output: { filename: "[name].[contenthash].js" },
};

Other bundlers can do the same; check your tool's documentation. The HTML then references the hashed names:

<link rel="stylesheet" href="/assets/app.9d41b7c0.css">
<script type="module" src="/assets/app.3f9c2e1a.js"></script>
<img src="/img/p1234.7a8b21.webp" alt="Blue kettle" width="400" height="400">

Hashed files get a long lifetime and immutable; the HTML that names them is revalidated every time. MDN shows this pairing:

# /assets/* and /img/* (names contain a content hash)
Cache-Control: max-age=31536000, immutable

# /products/1234 (the HTML)
Cache-Control: no-cache
ETag: "page-v91"

31536000 is one year in seconds, a conventional "as long as possible" and a choice, not a requirement.

Figure 4. A deployment under this strategy

How to read this: the HTML is the only mutable pointer. Revalidating it costs one small round trip and reveals the new bundle name; everything unchanged costs nothing.

Why it works:

1. The URL is the cache key. A long lifetime is dangerous only if a URL's content can change. Here a published URL always means the same bytes.
2. Only the entry point needs freshness. The small HTML is revalidated; the heavy files it points to are not.
3. A user gets old HTML with the old bundle or new HTML with the new one, never a mix, because the HTML decides which names load.

It makes one demand: old files must outlive the HTML that names them. A shopper's tab open since yesterday still holds yesterday's HTML. Delete yesterday's bundle on deploy and that tab breaks the next time it loads a lazy chunk.

What to cache for each kind of response

Ask two questions: does the URL change when the content does, and is the response the same for every user?

These are example policies, not rules; the numbers are placeholders. Choose lifetimes by asking how stale each response may be before someone is harmed, as in caching basics. A CDN may also apply its own rules on top of your headers, and defaults differ by provider.

Check what is really sent:

# Headers of the hashed bundle: look for Cache-Control and Age
curl -sI https://store.example/assets/app.3f9c2e1a.js

# Replay a validator; a 304 means the server honours conditional requests
curl -sI -H 'If-None-Match: "page-v91"' https://store.example/products/1234

The second command prints a 304 Not Modified status line only if the server still holds that exact ETag.

Reload, hard reload and "Disable cache"

These are browser behaviours, not part of the HTTP specifications, and they can differ between browsers and versions. The table follows MDN and Chrome's documentation at the time of writing.

The same modes exist in code as the cache option of fetch (MDN, Request.cache): { cache: "no-cache" } revalidates before using a stored copy, and { cache: "reload" } skips the cache for the request but stores the response. A hard reload is what developers press when something looks wrong; shoppers never do. Test a fix with a normal navigation in a profile that already holds the old version.

Service Workers and the Cache API: a different layer

A Service Worker is a background script that can intercept your page's requests; the Cache API is a store your JavaScript fills and empties. It is not the HTTP cache: it has no freshness rules, so whatever you put there stays until your code removes it. A service worker answers first; if it calls fetch(), the HTTP cache rules above still apply beneath it (web.dev). Offline support and update strategies are a separate topic.

Common caching bugs

Stale HTML pointing at deleted bundles. HTML is cached for long somewhere (a CDN rule, a heuristic) and a deploy removes the bundle names it mentions, leaving a blank page. Fix: no-cache HTML everywhere and keep old assets for a while.

Caching an error. A response is storable if its status is final and it carries an explicit lifetime such as max-age (RFC 9111 section 3), so a blanket one-year rule under /assets/ also covers a 404 or 503 from a bad deploy. A 404 is even heuristically cacheable with no header. Fix: long lifetimes only on success responses.

Caching a personalised response in a shared cache. The CDN stores shopper A's logged-in page and serves it to shopper B, usually because of public, an s-maxage, or a CDN rule that overrides the origin. Fix: private on anything user-specific.

In practice: caching for an online store's front end

The situation

A mid-sized store has a React single-page front end, a Node.js API and a CDN in front of both, owned by a small platform team. The build produces app.js and app.css at fixed names. Years ago someone added a CDN rule: "cache everything for one hour". Support now hears that after releases some shoppers "see old prices" or "get a blank page until they clear the cache".

Starting architecture

Figure 5. The store before the fix: one blanket rule

How to read this: three kinds of response needing very different freshness pass through one rule, which overrides the origin's own headers, so the application cannot say what it wants.

Options considered

The decision

Rollout and verification

Roll out in stages: ship hashed file names with the old rule still in place; publish the new headers for hashed files; switch HTML to no-cache with an ETag; remove the blanket rule. At each step run curl -sI against the CDN URL, not only the origin, and watch the hit ratio per path group, the share of 304s on HTML, script errors and 404s on /assets/. Add a pipeline test that fails the build if the Cache-Control of one hashed file, the HTML and one API URL differs from the expected value; header policy drifts silently otherwise.

The 2 a.m. failure

A release ships at 02:00. A clean-up job written to save storage deletes the previous release's bundles immediately. One legacy HTML path, the landing page, still carries an s-maxage from the old rule and sits in the CDN for up to an hour.

Figure 6. What the browser sees after the clean-up

How to read this: the failure needs two mistakes at once, a cached HTML page and a deleted asset. Either alone is survivable.

The alert is "script load errors up and 404s on /assets/ rising right after a release". First three checks: request the landing page through the CDN and read Cache-Control and Age; compare the bundle name in that HTML with the files on the origin; list the paths still matched by the old CDN rule. Mitigation: purge the affected HTML paths and redeploy the previous bundles. Follow-ups: retain the last few releases' assets, delete the legacy rule, and keep the header test.

Architect's notes

• Decide freshness per response type first. Hashed assets, HTML, public data and personal data are four policies; one rule for all is the root of most caching incidents.
• Treat headers as an interface. Cache-Control is a contract with every cache downstream. Review it like an API and test it in CI.
• Know which layer you are debugging. Browser, CDN and service worker cache independently; read Age and the response's Cache-Control first.
• Defer extensions. Add stale-while-revalidate or stale-if-error when a measured problem calls for them, after confirming support.
• Measure. CDN hit ratio, the share of 304s on HTML, repeat-visit transfer size and error rates after deploys; Loading Performance and Core Web Vitals covers wider measurement.

Common mistakes

• Reading no-cache as "do not cache". It means "store, but revalidate". Use no-store to prevent storage.
• Long lifetimes on HTML, or on URLs that never change name.
• Relying on heuristic freshness, which is each browser's guess.
• A timestamp or build number instead of a content hash, which defeats reuse.
• Blanket headers on every response, errors included.
• Testing only with a hard reload or "Disable cache".

Key takeaways

• A cached response is fresh (reuse, no request) or stale (revalidate or refetch). Lifetime comes from s-maxage, then max-age, then Expires.
• Validators (ETag, Last-Modified) make revalidation cheap; a 304 saves bandwidth but still costs a round trip.
• no-cache means "revalidate before reuse"; no-store means "do not keep it".
• immutable (RFC 8246), stale-while-revalidate and stale-if-error (RFC 5861) are extensions: check browser and CDN support.
• Fingerprint file names, give hashed files a long lifetime and immutable, serve HTML with no-cache and an ETag, and keep old assets until no cached HTML can name them.
• private keeps responses out of shared caches; s-maxage is read only by shared caches.
• A hard reload hides real behaviour; test as a returning user.
• The header sets here are example policies; derive yours from how stale each response may be.

Practice exercises

Exercise 1 — Starter (30 min): In DevTools on any site, find one script, one image and the HTML document. Write down their Cache-Control, ETag or Last-Modified, and Age. For each, say which freshness rule applies and whether the name suggests fingerprinting.

Exercise 2 — Intermediate (90 min): Write a small local server with a hashed asset, an HTML page and a JSON API, each with a policy from the decision table and an ETag on the HTML and API. Use curl -sI with and without If-None-Match to confirm you get 304 where expected, then observe a normal reload and a hard reload in the browser.

Exercise 3 — Advanced (half day): Reproduce the 2 a.m. failure locally: serve HTML with a shared-cache lifetime, change the bundle name, delete the old file, and watch a browser holding the old HTML fail. Fix it two ways (headers, and retaining old assets) and say which you would ship first and why.

Related reading

In this course:

• The Critical Rendering Path — how bytes become pixels, and what blocks what.
• Rendering Strategies: CSR, SSR, SSG, ISR and Streaming — where and when HTML is produced.
• Loading Performance and Core Web Vitals — how to measure loading, interaction and stability.

Elsewhere on the site:

• System Design: Caching Basics — back-end cache layers, TTLs and what not to cache.
• System Design: Advanced Caching — stampedes, invalidation and stale-while-revalidate on the server side.
• System Design: CDN and Object Storage — shared caches, cache keys and versioned URLs from the infrastructure side.
• System Design: Request Lifecycle — a request's full path through DNS, load balancers and servers.

Official documentation

• RFC 9111: HTTP Caching — freshness, validation, Vary and the core Cache-Control directives.
• RFC 5861: HTTP Cache-Control Extensions for Stale Content — stale-while-revalidate and stale-if-error.
• RFC 8246: HTTP Immutable Responses — the immutable directive.
• MDN: HTTP caching — private and shared caches, heuristic caching, reload behaviour and versioned URLs.
• MDN: Cache-Control — directive-by-directive reference.
• web.dev: Keeping things fresh with stale-while-revalidate — browser behaviour and service worker interaction.