#Incremental Static Regeneration (ISR)¶

ISR gives you the speed of static HTML with the freshness of dynamic rendering, by regenerating pages in the background when they grow stale.

The Mental Model¶

Enabling It¶

Set revalidate on the page (in seconds):

1// app/news/page.tsx
2export const revalidate = 60;       // revalidate at most every 60s

Or on a fetch:

1const data = await fetch("https://api.news.com/headlines", {
2  next: { revalidate: 60 },
3});

On-Demand ISR¶

You don't have to wait for the timer:

1// app/api/revalidate/route.ts
2import { revalidatePath, revalidateTag } from "next/cache";
3
4export async function POST(req: Request) {
5  const { path, tag, secret } = await req.json();
6  if (secret !== process.env.REVALIDATE_SECRET) {
7    return new Response("Unauthorized", { status: 401 });
8  }
9
10  if (path) revalidatePath(path);
11  if (tag)  revalidateTag(tag);
12
13  return Response.json({ revalidated: true });
14}

The CMS posts to this endpoint when a writer publishes. Within milliseconds, the new article is live worldwide.

Per-Request vs Background Regen¶

ISR's promise: no visitor ever waits for a regeneration. The stale page is served instantly; regen happens after the response is flushed.

Exception: the very first time a page is requested (cache miss), the user waits for the initial render. Use generateStaticParams to prebuild your hot pages.

ISR + Tags¶

1// lib/data/posts.ts
2"use cache";
3import { cacheTag, cacheLife } from "next/cache";
4
5export async function getPost(slug: string) {
6  cacheTag("post", `post:${slug}`);
7  cacheLife("hours");
8  return db.post.findUnique({ where: { slug } });
9}

When the writer edits a post:

1revalidateTag(`post:${slug}`);    // wipes the cache for that post only

Subsequent visitors see the updated content. Visitors to other posts continue to hit cache.

ISR On Vercel vs Self-Hosted¶

• Vercel handles ISR storage and propagation across edge nodes automatically. Nothing to configure.
• Self-hosted (Node.js, Docker, Kubernetes) ships ISR with the filesystem as the cache. Multi-instance deployments need a shared cache:

1// next.config.ts
2const config: NextConfig = {
3  cacheHandler: require.resolve("./cache-handler.js"),
4  cacheMaxMemorySize: 0,    // disable in-memory; rely on shared layer
5};

Popular shared backends: Redis, S3, Cloudflare KV.

When ISR Is Not the Right Choice¶

• Personalized content — ISR shares a cache key, so per-user data leaks. Use dynamic rendering.
• Strict consistency required — ISR is eventually consistent. For a banking app, render dynamic.
• Very low traffic — if a page is hit only once a day, ISR's freshness window doesn't help. Make it dynamic and cache the DB query instead.