How it works

The explanation, with examples you can run.

Freshness

A stored response is fresh until its age passes max-age seconds. A fresh response is used straight from the cache, with no network request at all. Once it is stale, the cache must revalidate before using it. Useful directives:

max-age=N: fresh for N seconds. s-maxage=N does the same for shared caches only, overriding max-age there.
public / private: private means only the user's browser may store it (personalised pages); shared caches must not.
no-cache: may be stored, but must be revalidated before every use.
no-store: must not be stored anywhere.
immutable: the response won't change while it is fresh, so don't revalidate even when the user reloads.
stale-while-revalidate=N: after it goes stale, it may still be served for N seconds while a fresh copy is fetched in the background.

Without Cache-Control or Expires, caches may guess a freshness lifetime from Last-Modified (heuristic caching). Set the headers yourself rather than relying on that.

Revalidation

When the server sends an ETag (a version tag for the body) or Last-Modified, a cache holding a stale copy sends a conditional request with If-None-Match or If-Modified-Since. If the content hasn't changed, the server answers 304 Not Modified with headers only, and the cache updates its stored copy with them, which makes it fresh again. You still pay a round trip, but not the download.

Your code

// What a cache does with a stored response when the same URL is asked for again.
function parse(cacheControl) {
  const out = {}
  for (const part of cacheControl.split(",")) {
    const [key, value] = part.trim().toLowerCase().split("=")
    if (key) out[key] = value === undefined ? true : Number(value)
  }
  return out
}

function decide(cacheControl, ageSeconds, shared) {
  const cc = parse(cacheControl)
  if (cc["no-store"]) return "not stored: go to the server"
  if (shared && cc["private"]) return "shared cache may not store it: go to the server"
  if (cc["no-cache"]) return "stored, but revalidate first (If-None-Match)"
  const lifetime = shared && cc["s-maxage"] !== undefined ? cc["s-maxage"] : cc["max-age"] ?? 0
  return ageSeconds < lifetime ? "fresh: use it, no request" : "stale: revalidate (If-None-Match)"
}

const cases = [
  ["public, max-age=31536000, immutable", 86400, false], // app.3f9a1c.js
  ["no-cache", 5, false],                               // index.html
  ["max-age=60, s-maxage=600", 300, true],              // an API response at a CDN
  ["max-age=60, s-maxage=600", 300, false],             // the same, in the browser
  ["private, max-age=600", 10, true],                   // a user's account page at a CDN
  ["no-store", 0, false],                               // a bank statement
]
for (const [cc, age, shared] of cases) {
  console.log(`${shared ? "CDN    " : "browser"} | ${cc} | age ${age}s -> ${decide(cc, age, shared)}`)
}

// Revalidation: the cache sends the ETag it has; a match means 304 Not Modified, no body.
const current = '"v7"'
const ifNoneMatch = '"v7"'
console.log(ifNoneMatch === current ? "304 Not Modified: reuse the stored body" : "200 OK with a new body")

⌘/Ctrl + Enter

OutputNot run yet

Press Run to see what your code prints, in order.

Runs in this browser, in an isolated frame with no access to this page. console.log, info, warn and error are shown; code runs as a classic script, so use an async function for await.

This is a simplification of RFC 9111 (it ignores Expires, Vary and heuristics), but it is the decision every cache makes.

A pattern that works

Hashed static assets (app.3f9a1c.js, logo.81b2.svg): public, max-age=31536000, immutable. Your build tool writes the hash; a deploy changes the URL.
HTML: no-cache with an ETag, or a short max-age at the CDN, so a new deploy is picked up on the next visit.
Personalised responses: private, and no-store for anything sensitive.
Responses that differ by request header (language, encoding): send Vary so a cache doesn't hand one user's variant to another.

A CDN is a shared cache close to the user. It follows the same headers, can be purged when you must, and usually adds its own controls on top. Purging is the escape hatch; hashed URLs are the plan.

Check yourself

3 questions. Get them all right to finish this topic.

1.Which headers suit app.3f9a1c.js, a file whose name changes whenever its content does?
2.And for index.html, which links to those hashed files?
3.An API response has Cache-Control: max-age=60, s-maxage=600. What does s-maxage change?

0 of 3 right so far. Get all three to finish this topic.

HTTP caching for the web

How it works

Freshness

Revalidation

A pattern that works

Check yourself

Go deeper