Caching: the cheapest performance work, and the easiest to get wrong

A request passes through four or five caches before it reaches your code, and each one obeys different rules. Most caching bugs come from reasoning about one layer while a different layer is the one actually answering.

The layers, in the order a request meets them

Two classes of response, two policies

Almost all of the confusion dissolves once you separate responses whose URL changes when the content changes from responses whose URL stays the same.

# Content-hashed assets: /_next/static/chunks/main.a91f3c.js
# The URL changes when the bytes change, so a cached copy is never wrong.
Cache-Control: public, max-age=31536000, immutable

# HTML documents: /pricing
# Same URL, changing content. Never let a browser hold this for long.
Cache-Control: public, max-age=0, s-maxage=600, stale-while-revalidate=86400

# Anything personalised or authenticated.
# private keeps it out of shared caches; no-store keeps it out of all of them.
Cache-Control: private, no-store

The middle case is the interesting one. The zero max-age tells browsers to revalidate on every visit; s-maxage lets the CDN answer from the edge for ten minutes; stale-while-revalidate lets the CDN keep serving the old copy for a day while it fetches a fresh one behind the request. No visitor waits for a regeneration, and the origin sees a fraction of the traffic.

Vary, and how shared caches leak

A CDN keys its cache on the URL. If a response differs by anything other than the URL — a cookie, a language header, a device class — the cache must be told, or it will hand one visitor's response to another.

• Vary: Accept-Encoding is almost always correct, and usually handled for you
• Vary: Accept-Language is correct if you negotiate language, but distinct URLs per locale are better — they are cacheable, linkable and indexable
• Vary: Cookie effectively disables shared caching, since nearly every visitor has a different value. If a response depends on a cookie, mark it private instead of varying on it
• Never Vary: User-Agent — the cardinality is unbounded and the hit rate collapses to nothing

The failure mode worth fearing is a route that is public for anonymous visitors and personalised once signed in, served under a single cacheable policy. The first signed-in visitor populates the edge with their own page and everyone after them receives it. Split the route, move the personalisation to a client fetch, or mark it private — but do not expect Vary: Cookie to rescue the design.

Invalidate by tag, not by guessing

Time-based expiry is a bet that staleness for some number of seconds is acceptable. Tag-based invalidation removes the bet: when the underlying data changes, everything derived from it is dropped.

// Tag on read, so each cached artefact records what it depends on.
const product = await fetch(`${api}/products/${id}`, {
  next: { tags: ["products", `product:${id}`], revalidate: 3600 },
});

// Purge on write — from the handler that changed the data, not from a
// scheduled job that hopes to catch it later.
import { revalidateTag } from "next/cache";

export async function onProductUpdated(id: string) {
  revalidateTag(`product:${id}`);  // the detail page
  revalidateTag("products");        // every listing that includes it
}

Two tags per entity — one specific, one collection-wide — covers the case people forget. Updating a price purges the product page and leaves the category listing quoting the old figure, unless the listing carries the collection tag too.

What should never be cached

• Responses to authenticated requests, unless the cache key includes the identity — and preferably not even then
• Anything carrying a token, a session identifier or a single-use link
• Error responses, beyond a few seconds — a cached 500 turns a transient fault into a sustained outage
• Results of requests that changed state; a POST response is not a cacheable document
• Redirects whose destination depends on the visitor, such as a locale or authentication bounce

The cached-error case deserves the emphasis. If a dependency fails briefly and the edge stores the resulting 503 for ten minutes, the incident outlives its cause by ten minutes on every route that touched it. Give error responses an explicit short policy rather than letting them inherit the success policy.

Measure the hit rate, not the configuration

Caching is one of the few areas where correct-looking configuration and working behaviour diverge silently. The only reliable check is to observe what the edge actually did.

1. 01Request a page twice and read the CDN's cache-status header. A second request still reporting a miss means something is preventing storage — usually a Set-Cookie on the response.
2. 02Confirm content-encoding is present. An uncompressed response is roughly three times the bytes, and some origins compress only when asked.
3. 03Check the hit rate per route rather than in aggregate. A 95% overall figure can conceal a heavily trafficked route sitting at zero.
4. 04Deploy, then verify that hashed assets were not re-requested and that HTML was. That is the whole policy, tested in one observation.

Done properly the result is unglamorous: the origin serves a small share of requests, most visitors are answered from a nearby edge, and a content change appears everywhere within seconds because the purge runs where the write does.