Incremental Static Regeneration

A statically generated page is fast because it is a file: no query, no render, one cache lookup. Its weakness is that a change in the data needs a new build. For a catalogue of three books that is acceptable; for a catalogue of one hundred thousand products it is not. Incremental Static Regeneration keeps the speed of static files and removes the rebuild:

The mechanism is stale-while-revalidate, the same idea as the HTTP directive of that name. A cache entry is fresh until its revalidation time has passed. After that it is stale: the next request still gets the stale copy immediately, and that same request starts building a new copy in the background. When the new copy is ready it replaces the old one, and requests after that get the new copy. Nobody ever waits for a render, except for the very first visit to a page that was never generated, and after the entry has expired (see below).

Two details of the diagram matter in practice. First, regeneration produces both artifacts of a route, the HTML for the first load and the RSC payload that the client router uses for navigations (see Server and Client Components), and stores them in the same entry so that a hard load and a client navigation never disagree. Second, nothing in this loop is a timer: regeneration is triggered by a request. A page nobody visits is never regenerated, which is why a revalidation time is "at most once every N seconds", not "every N seconds".

An entry has three lifetimes, and the names differ between the two models but the shape is the same:

The revalidate time says when a copy turns stale. The expire time says when a stale copy is too old to serve at all, so the next request blocks on a render instead. The default expire is one year, which in practice means "never block". The x-nextjs-cache response header of a self-hosted next start server shows where an entry is: HIT (served from cache), STALE (served from cache while a regeneration runs), MISS (not in the cache, rendered now) and REVALIDATED (regenerated by on-demand revalidation). Treat it as a diagnostic, not as an API.

Source: Incremental Static Regeneration, How revalidation works

ISR is a feature of a long-running Node.js server (or of a platform that emulates one), not of the build and not of the browser. The matrix below is the part that surprises people who come from static hosting.

Two rules follow. Verify with a production build: next build followed by next start is the only way to see STALE and HIT. And the cache lives where the server lives: with one instance and a persistent disk it just works, with several instances or ephemeral compute you must plan for it (see Self-Hosting and Multiple Instances).

Source: ISR caveats and platform support, Self-hosting: Caching and ISR

The Bookshelf keeps its book data in a CMS. The front end shows /books/1, /books/2, …​ and a /shelf page that lists everything. Editors change prices; the site must follow within seconds, but a visitor must never wait for the CMS. That is ISR. To keep the experiments reproducible, the CMS is replaced by a JSON file that "an editor" changes behind the application’s back.

The application reads it over HTTP, like it would read a real CMS, through a Route Handler. connection() makes the handler dynamic under both caching models (without it, Cache Components would prerender a GET handler that touches no request data).

Because next build calls the CMS while it prerenders, the CMS must answer during the build. A real, hosted CMS does. For the local experiment a 12-line Node script served the same JSON on the port of the later next start for the duration of the build; the running server then answered the same URL from the Route Handler above. Editing a price is one line of script:

And a small shell helper prints one line per request: the time, the status, the x-nextjs-cache header, the price and the "Rendered at" stamp of the page. Reading the stamp is the whole trick: the same stamp means the same copy. The time column is in UTC, like the stamps.

Source: ISR and route.js

Without cacheComponents (the default in 16.3), a page is static if nothing in it needs the request, and ISR is switched on by giving it a lifetime. There are three ways to do that and they combine.

With cacheComponents: true the unit of caching moves from the route to the function or component. The route segment revalidate is no longer allowed (nor is dynamic or dynamicParams): the build stops with

(dynamicParams produces the same message). The lifetime now lives next to the data, through the 'use cache' directive, cacheLife and cacheTag. The page itself becomes a partially prerendered shell: the parts that are cached or static are in the shell, everything else streams in (see Streaming and Suspense).

Date is allowed inside a 'use cache' function because the result is cached on purpose, so the stamp is the time of the cache entry, which is what the experiments below read. The page reads params inside a <Suspense> boundary, as Cache Components requires for routes whose params are not all known:

The extra ◐ /books/[id] row is the App Shell of the route, the generic part of the page that does not depend on the id. The stale-while-revalidate cycle is identical to the previous model, with the lifetimes now coming from the profile (expire: 3600 shows up as stale-while-revalidate=3595):

Time-based ISR is a guess about how often data changes. When you know (a Server Action ran, a CMS webhook arrived) you invalidate on demand. Five functions exist; they live in next/cache (refresh too) and differ in where they may be called, what they target, and, crucially, whether the next visitor waits.

None of them can be called from a Client Component or from Proxy. A revalidation is triggered by a request, not by the call: invalidating a tag marks entries, and each page regenerates when it is next visited (a revalidatePath with a dynamic pattern does not run hundreds of renders at once).

The usual producer of "I know the data changed" is not your application but a CMS: the editor presses Publish and the CMS calls a URL of yours. That URL is a public endpoint that changes server state, so treat it like one: verify who is calling, accept only identifiers you can validate, and never let the payload name arbitrary tags or paths. The handler below checks an HMAC-SHA256 signature of the raw body (most CMS products sign webhooks this way, or send a shared-secret header), compares it in constant time, validates the id, and invalidates tags the application defines. updateTag is unavailable here, so it uses revalidateTag(tag, 'max').

Keep the secret in an environment variable on the server (see Configuration, TypeScript and Environment Variables), never with a NEXT_PUBLIC_ prefix. The experiment signed the body the way the CMS would and used the /shelf page, which has no lifetime of its own (it is static and changes only on invalidation):

The page was served from cache until the webhook arrived, then once stale, then fresh; it never blocked a visitor. Two design points: the /shelf list carries the tag books, so a book.published event refreshes it while a book.updated event refreshes only the page of that book; and the handler returns quickly, because the CMS usually retries slow or failing webhooks.

Source: revalidateTag in a Route Handler, Revalidating

Next.js writes Cache-Control for you according to the kind of route, and a CDN can use it:

The second number of the ISR value comes from the expire time. Under Cache Components it is the profile’s expire (3600 gave stale-while-revalidate=3595). In the previous model it defaults to one year and can be lowered for every ISR page with the top-level expireTime option in next.config (seconds):

Built with that setting, the page with revalidate = 5 answered Cache-Control: s-maxage=5, stale-while-revalidate=3595 (an hour minus the 5 seconds), and the Pages Router table printed /legacy/[id] 5s 1h in the Expire column. The official example: a revalidate of 15 minutes with an expire time of one hour gives s-maxage=900, stale-while-revalidate=2700.

A CDN in front of Next.js has three jobs to get right:

Rolling deployments add version skew (a client of deploy A talking to a server of deploy B). Setting deploymentId makes the client do a hard navigation when the server’s deployment differs, instead of mixing payloads.

Source: expireTime, CDN caching, How revalidation works

ISR and the fetch data cache use the same server cache. By default it is an in-memory store (50 MB) backed by the local disk of each instance. That is perfect for one next start process with a persistent disk. It breaks three assumptions as soon as you scale:

The remedy is a shared cache plus shared tag state. There are two handler options, for two different caches:

For Cache Components, the two hooks that matter for coordination are updateTags(), called when revalidateTag() runs and which should write the invalidation event to shared storage (Redis, a database), and refreshTags(), called before each new request and which should read recent events back and update local tag state. Catch errors inside refreshTags(): if it throws, the request fails; if it catches, requests continue on the last known state and may serve stale content until connectivity returns. A cache read failure must be signalled by returning undefined (a cache miss), not by throwing. Soft tags (names such as N_T/books/[id]/page, generated from the route path) are how revalidatePath rides on the same tag mechanism.

The code below is a runnable cacheHandler skeleton in the shape of the reference, with one lesson learned by running it on 16.3.8: page entries do not carry their tags in ctx.tags. A handler that indexes only ctx.tags, as a quick reading of the guide suggests, never invalidates a page. The tags of an APP_PAGE value travel in the x-next-cache-tags header of the value (a comma-separated string), for the page of book 1: N_T/layout,N_T/books/layout,N_T/books/[id]/layout,N_T/books/[id]/page,N_T/books/1,books,book:1.

Run with it, the page behaved as before: MISS on the first request (the build-time seed is not in the handler’s store), HIT on the next, the webhook for book:1 deleted the entry through revalidateTag(["book:1"]) and the following request regenerated it (MISS, new price) and was HIT again. Two caveats from that run: this handler deletes on invalidation, so the max profile’s stale-while-revalidate becomes a blocking render (a production handler keeps the entry and marks it stale to preserve it), and a Map is not shared, so for several instances the store must be an external service.

Other parts of a multi-instance deployment that bite ISR users:

Source: Self-hosting: Caching and ISR, Multi-Instance Cache Coordination, Custom Next.js Cache Handler, cacheHandlers, How revalidation works: multi-instance

ISR was introduced for the Pages Router in 9.5; the model is identical, the surface is different. A page exports getStaticPaths (which paths to prerender and what to do with the rest) and getStaticProps (the data, and the revalidate time).

The build prints the lifetime in the Pages Router table, and the run shows the same cycle (the pages and the app directory happily coexist in one project):

getStaticProps returns props, redirect or notFound, plus an optional revalidate (seconds; the default false means never). notFound: true yields a 404 even if the page existed before (a deleted post), and obeys the same revalidate. context.revalidateReason tells the function why it runs: "build", "stale" or "on-demand".

The fallback values of getStaticPaths map onto what you already know:

(fallback: true is not supported with output: 'export', and it does not update generated pages: ISR does.)

On the Bookshelf: the book detail pages and the catalogue use cacheTag('books', 'book:<id>') with a cacheLife of a few minutes as a safety net, the CMS webhook calls revalidateTag(…​, 'max'), the admin "Publish" Server Action calls updateTag, and a price shown in a cart or at checkout is never taken from an ISR page at all (prices are re-read on the server when the order is created, see the security pages of this section).

A failing regeneration deserves its own measurement, because it is the property that makes ISR safe in front of a flaky CMS. The CMS was made to answer 500 after the page had been cached, and getBook throws on a non-OK response:

and the server log held Error: CMS answered 500. Cache Components behaved the same way (the stale 66.66 EUR copy was served through two failed intervals, and 77.77 EUR appeared after the CMS recovered). Without it a thrown error would have become the cache entry or a 500 for the visitor. Debugging helpers: logging.fetches.fullUrl in next.config prints fetch cache hits and misses, and NEXT_PRIVATE_DEBUG_CACHE=1 in the environment of next start logs every server cache read and write, for example FileSystemCache: get /route-cache/APP_PAGE/<hash>/$/books/2 APP_PAGE true and the matching set (the key is opaque: preserve it whole in a custom handler).

Source: ISR: handling uncaught exceptions, ISR: troubleshooting, blocking-prerender-dynamic

Rendering Fundamentals places ISR among CSR, SSR and SSG, Server-Side Rendering is the per-request alternative, and the sibling pages on static site generation, Partial Prerendering and Cache Components in this section cover the build-time half and the shell in more depth; the caching and data-fetching pages that follow in the section cover 'use cache' and fetch in full. The React side of server rendering is in React: Server Rendering, SSG and React Server Components, and the backend counterpart of Route Handlers and webhooks is compared in NestJS vs Next.js.