ISR and CDN layers: stale-while-revalidate at origin, per-pod caches, and purge ordering

ISR is stale-while-revalidate at the origin

revalidate: 60 does not mean “regenerate every 60 seconds” and it does not mean “users wait for fresh HTML”. It is stale-while-revalidate implemented at the origin: every cached entry carries a timestamp, and the first request after the window expires is served the stale page immediately — single-digit milliseconds from cache — while exactly one regeneration kicks off in the background. When the render finishes, the new entry swaps atomically: no request ever sees a half-written page. If the regeneration throws, the swap simply does not happen — the last good page keeps serving and the next request after the window retries. The serving math is what makes ISR attractive at all: a cache hit is 1–5 ms of IO, a full regeneration is whatever your page render costs — typically 100–800 ms of data fetching and RSC work — and under ISR nobody waits for it except the regeneration itself.

// app/pricing/page.tsx — time-based: at most one regen per 60 s window
export const revalidate = 60;

// or per-fetch, with tags for on-demand invalidation:
const res = await fetch('https://cms.example.com/prices', {
  next: { revalidate: 60, tags: ['pricing'] },
});

// app/api/cms-webhook/route.ts — on-demand: invalidate now, not on a timer
import { revalidateTag } from 'next/cache';
export async function POST() {
  revalidateTag('pricing'); // marks entries stale — IN THIS PROCESS ONLY
  return Response.json({ ok: true });
}

More than one pod: the cache must be shared

Everything above is true per process. The default ISR store is a filesystem cache under .next/cache plus an in-memory LRU — pod-local on both counts. One pod, one truth. Three pods, three truths: each regenerates on its own schedule, so time-based pages drift a window apart — usually tolerable. What is not tolerable is on-demand revalidation: revalidatePath and revalidateTag mutate the local store of whichever pod ran them. The webhook lands on pod B, pod B regenerates, pods A and C never hear about it — and a round-robin balancer turns that into the flip-flop from the hook, fresh and stale alternating per request. With no time-based fallback the stale pods never converge at all.

Two production-grade fixes. The structural one: replace the store with a shared cacheHandler — next.config.js accepts cacheHandler: require.resolve('./cache-handler.mjs') plus cacheMaxMemorySize: 0 to disable the per-pod LRU, and your handler implements get/set/revalidateTag against Redis or another shared store. Now there is one truth again; the price is ~1–3 ms of Redis RTT on every ISR hit instead of sub-millisecond local disk — the cost of consistency. The alternative keeps local caches but fans out the invalidation: the webhook publishes to Redis pub/sub, every pod subscribes and calls revalidateTag locally. Fan-out keeps hits at local-disk speed but reintroduces a distributed-systems problem — a pod that was restarting during the publish missed it, and nothing reconciles. The shared store gives you correctness by construction; fan-out gives you speed at the cost of a reconciliation gap you must monitor. Shared store is the boring, correct default; fan-out is the optimization you adopt with monitoring.

The CDN layer on top — and purge ordering

In front of the pods sits a CDN, and ISR pages advertise themselves to it: a route with revalidate: 300 is served with Cache-Control: s-maxage=300, stale-while-revalidate — the CDN may cache it for five minutes and serve stale while it refetches. A healthy content site runs 80–98% CDN hit ratio, which means your pods see only the trickle of misses; the CDN is doing the same stale-while-revalidate dance one layer up, against your origin instead of against your render function. Two caches, same protocol, stacked.

Stacked caches have an ordering theorem, and violating it is the second classic incident: regenerate the origin first, purge the CDN second. Run it in the wrong order and walk the timeline: purge completes, the CDN is empty, every request for the page is now a miss hitting your origin — a thundering herd of misses — and the origin, which has not regenerated yet, dutifully serves the old page under SWR semantics. The CDN caches that old page again, stamped with a fresh s-maxage=300, and your “urgent fix” is now pinned for another full window — you purged, and the stale content came straight back. The correct sequence: trigger revalidateTag/revalidatePath on the origin (reaching every pod, per the previous section), confirm the origin serves fresh, then purge the CDN so the resulting misses pull the new page. The herd still happens — that is what purges cost — but it pulls the right bytes.