Incremental Static Regeneration (ISR) Explained with Examples (2025 Guide)

Static-site generation (SSG) gives you blazing-fast pages, but the moment your data changes you need a full rebuild… unless you use Incremental Static Regeneration (ISR). ISR lets a page stay static and quietly refresh in the background—no global rebuild, no slow users. Below is a 2025-focused guide that covers how ISR works in both the Pages Router and the newer App Router, shows on-demand revalidation, and finishes with best-practice tips.

1. What problem does ISR solve?

• SSG → great performance, stale quickly.

• SSR (or RSC “force-dynamic”) → always fresh, slower TTFB under load.

• ISR sits between: serve a cached HTML file instantly, then — at a schedule you pick or on-demand — rebuild that single page in the background. Users never see the rebuild. nextjs.org

2. How ISR works under the hood

1. First request after a build returns the pre-rendered HTML.

2. Revalidation clock starts (e.g., 60 s).

3. After the revalidation window expires, the next request triggers a background regeneration while still getting the stale HTML (stale-while-revalidate).

4. Once the new HTML finishes, Vercel (or your host) swaps it in; future requests get the fresh page. nextjs.org

3. Using ISR in the Pages Router (/pages)

3.1 Timed revalidation (revalidate)

// pages/blog/[slug].tsx import { GetStaticProps, GetStaticPaths } from 'next'; export const getStaticPaths: GetStaticPaths = async () => { const slugs = await fetchCMSslugs(); return { paths: slugs.map(s => ({ params: { slug: s } })), fallback: 'blocking' }; }; export const getStaticProps: GetStaticProps = async ({ params }) => { const post = await fetchCMSpost(params!.slug as string); return { props: { post }, revalidate: 60, // seconds – regenerate at most once per minute }; }; export default function Blog({ post }) { /* … */ }

fallback: 'blocking' shows nothing until the first HTML is ready, avoiding an empty shell. ryanschiang.com

3.2 On-demand ISR (Build-free)

Need instant refresh (e.g., when an editor clicks “Publish”)? Hit an API route that calls res.revalidate('/blog/my-slug'):

// pages/api/revalidate.ts import type { NextApiRequest, NextApiResponse } from 'next'; export default async function handler(req: NextApiRequest, res: NextApiResponse) { const { secret, path } = req.query; if (secret !== process.env.REVALIDATE_TOKEN) return res.status(401).json({ msg: 'Unauthorized' }); await res.revalidate(path as string); res.json({ revalidated: true }); }

Now a CMS webhook can POST to /api/revalidate?secret=...&path=/blog/my-slug. geeksforgeeks.org

4. Using ISR in the App Router (/app)

App-Router pages are static by default. You enable ISR with the revalidate option on fetch or by exporting a revalidate number.

4.1 Page-wide revalidate

// app/blog/[slug]/page.tsx export const revalidate = 120; // seconds export default async function BlogPage({ params }) { const post = await fetch(`https://cms.io/posts/${params.slug}`, { next: { revalidate }, // 👈 passes the same value to fetch cache }).then(r => r.json()); return <Article post={post} />; }

4.2 Tag-based on-demand ISR (Next 14)

Next 14 lets you group pages by cache tags and revalidate them together, without hard-coding paths:

// Fetch with a tag await fetch(url, { next: { tags: ['blog'] } }); // Revalidate all ‘blog’ pages from an action/route import { revalidateTag } from 'next/cache'; export async function POST() { revalidateTag('blog'); return Response.json({ ok: true }); }

Great for multi-locale or multi-tenant sites. dev.toemirbalic.com

5. ISR + Edge Functions (2025 status)

• Pages Router ISR runs in Node serverless, not Edge.

• App Router pages delivered from the Edge can still regenerate in a regional worker; the new HTML is globally propagated via Vercel’s cache. This “Edge-delivered, Node-regenerated” combo landed in early 2025. emirbalic.com

6. Practical patterns & gotchas

7. Example: Building a static product catalogue that updates hourly

// app/products/page.tsx import { fetchProducts } from '@/lib/api'; export const revalidate = 3600; // 1 hour export default async function Products() { const products = await fetchProducts({ next: { revalidate } }); return ( <ul className="grid gap-6 md:grid-cols-3"> {products.map(p => ( <li key={p.id} className="border p-4 rounded-xl"> <h3>{p.name}</h3> <p>{p.price} ₹</p> </li> ))} </ul> ); }

Hook up a webhook from your inventory system to revalidateTag('products') to force a refresh the moment a price changes.

8. Best practices for 2025

1. Think per-page — give marketing landing pages long TTLs, while the blog gets 1–5 min.

2. Protect revalidate tokens — keep them in env vars; rotate periodically.

3. Log regeneration times — Vercel functions show rebuild duration; watch for API bottlenecks.

4. Combine with drafts — editors preview via SSR, publish via on-demand ISR.

5. Monitor cache hit-rate — use x-vercel-cache header to spot forced SSR.

6. Edge where it helps — global low-latency read, Node for the heavy rebuild. github.com

9. Conclusion

ISR lets you enjoy the speed of static with the flexibility of dynamic content—a must-know technique for modern Next.js sites. Whether you’re on the older Pages Router or all-in on the App Router, the 2025 workflow is straightforward: set revalidate, tag strategically, and trigger rebuilds exactly when you need them. Happy regenerating! 🚀

Frequently Asked Questions (FAQ) — Incremental Static Regeneration (ISR)