How ISR works
ISR follows a stale-while-revalidate model. After the revalidation window passes, the next visitor still gets the cached, stale page immediately. If revalidation throws an error, Next.js keeps serving the last successfully generated data from the cache.
Time-based revalidation
In the Pages Router, ISR is enabled by returning revalidate from getStaticProps. In the App Router (previous caching model), exporting revalidate = 60 from a route segment invalidates the cache at most once every 60 seconds, when a request arrives.
On-demand revalidation
In the App Router, the
revalidatePathfunction invalidates cached pages. It only invalidates cache entries; the page is regenerated on the next request, not immediately.revalidateTaggives more granular invalidation of tagged data than revalidating whole paths.In the Pages Router, a page that relies only on on-demand revalidation has
revalidateset tofalseby default and is regenerated only whenres.revalidate()is called.
The Next.js ISR guide has code for each option. For how revalidation fits with getStaticProps and the other data-fetching methods, see Next.js pre-rendering and data fetching.
Limits and platform behavior
Runtime. ISR works only on the Node.js runtime, the default runtime.
Static export. ISR is not available in a static export (
output: 'export').Self-hosting. When you run multiple instances, the default file-system ISR cache is separate for each instance.
Debugging. The
x-nextjs-cacheresponse header shows how a page was served from the ISR cache.Vercel. The ISR cache persists content until you revalidate it or it goes unaccessed for 31 days.
With Cache Components (Next.js 16), a visit to a URL whose params were not prerendered gets the App Shell at once, and the full page is generated in the background. Stable ISR first shipped for the Pages Router in Next.js 9.5.0. To compare ISR with SSR, SSG and CSR, see Next.js rendering strategies.
What Pagepro tests on ISR sites
On Sanity projects, documents created by scripts, such as migrations, imports and exports, can skip the revalidation path that a Studio publish triggers, and their pages do not rebuild. Pagepro's rule is to test every non-Studio write path (script, API or agent) against revalidation on its own, because a working publish does not cover it. For revalidation problems on a live site, see Next.js support.
Sources
- GlossaryNext.js · nextjs.org
- How to implement Incremental Static Regeneration (ISR) - App RouterNext.js · nextjs.org
- Incremental Static Regeneration (ISR) - Vercel DocsVercel · vercel.com
- How to implement Incremental Static Regeneration (ISR) - Pages RouterNext.js · nextjs.org
- Incremental Static Regeneration with Cache ComponentsNext.js · nextjs.org