The Next.js ISR Handbook

The Prep List

You export an async function from your dynamic route's page.tsx. It returns an array of parameter objects—one per page you want pre-built. Each object is a dish that's ready before the doors open. Zero compute at request time.

dynamicParams: The Walk-In Order

Your prep list covered 80 guides. But someone just published guide #81—a dish that wasn't part of the original mise en place. A user hits /docs/new-feature. What happens?

1
// Build the page on first visit, cache it for everyone after
2
export const dynamicParams = true;  // default
3
 
4
// Reject unknown slugs with a 404
5
export const dynamicParams = false;

With true, the kitchen fires off the new dish on demand. First visitor waits for it to cook, but after that it's prepped and cached for everyone. The menu grows organically.

With false, the kitchen refuses walk-in orders. If it wasn't on the prep list, it's a 404. Locked down. Useful when you control every URL and don't want surprises.

Act 1: The Fresh Page

You deploy your site. Next.js has pre-built /products/blue-sneakers with the data it fetched at build time. The page is cached and ready. Every visitor gets the static version. Fast. Zero compute.

Act 2: The Clock Runs Out

Your revalidate is set to 3600 seconds. An hour passes. The page is now stale—but it's still cached. Nothing happens yet. Nobody's coming to the bakery.

Act 4: The Swap

The background rebuild finishes. Next.js replaces the cached page with the new one. Silently. No downtime. No flicker.

revalidatePath

Invalidate a specific route. The next visitor triggers a fresh build.

You can call it from a Server Action:

1
// app/actions/revalidate.ts
2
"use server";
3
 
4
import { revalidatePath } from "next/cache";
5
 
6
export async function purgeProductPage(path: string, secret: string) {
7
  if (secret !== process.env.REVALIDATION_SECRET) {
8
    throw new Error("Unauthorized");
9
  }
10
 
11
  revalidatePath(path);
12
}

Or from a Route Handler:

1
// app/api/revalidate-path/route.ts
2
import { revalidatePath } from "next/cache";
3
import { NextRequest, NextResponse } from "next/server";
4
 
5
export async function POST(request: NextRequest) {
6
  const { path, secret } = await request.json();
7
 
8
  if (secret !== process.env.REVALIDATION_SECRET) {
9
    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
10
  }
11
 
12
  revalidatePath(path);
13
  return NextResponse.json({ revalidated: true });
14
}

Same result either way. The cached version of that path is purged. The next visitor triggers a fresh build.

revalidateTag

Sometimes one data change affects multiple pages. A product's price updates, and it shows on the product page, the category page, and the homepage featured section. Revalidating each path manually? Tedious.

Tags let you group cache entries. When you fetch data, tag it. When the data changes, revalidate the tag—and every page using that data rebuilds.

1
// app/products/[slug]/page.tsx
2
export default async function ProductPage({
3
  params,
4
}: {
5
  params: Promise<{ slug: string }>;
6
}) {
7
  const { slug } = await params;
8
 
9
  const res = await fetch(`https://api.mystore.com/products/${slug}`, {
10
    next: { tags: [`product-${slug}`, "all-products"] },
11
  });
12
  const product = await res.json();
13
 
14
  return (
15
    <article>
16
      <h1>{product.name}</h1>
17
      <p>${product.price}</p>
18
    </article>
19
  );
20
}

1
// app/actions/products.ts
2
"use server";
3
 
4
import { revalidateTag } from "next/cache";
5
 
6
export async function updateProductPrice(slug: string, newPrice: number) {
7
  await fetch(`https://api.mystore.com/products/${slug}`, {
8
    method: "PATCH",
9
    body: JSON.stringify({ price: newPrice }),
10
    headers: { "Content-Type": "application/json" },
11
  });
12
 
13
  // Invalidate everything tagged with this product
14
  revalidateTag(`product-${slug}`);
15
}

One revalidateTag call. Every page that fetched data with that tag gets rebuilt on the next request. Clean.

Here's the cheat sheet:

• generateStaticParams pre-builds pages at build time. It's your guest list.
• revalidate sets the cache lifetime. It's your freshness knob.
• dynamicParams controls whether new pages can be generated on demand or get a 404.
• Time-based revalidation uses stale-while-revalidate: serve the old, build the new, swap when ready.
• On-demand revalidation with revalidatePath and revalidateTag lets you trigger rebuilds immediately.
• NEXT_PRIVATE_DEBUG_CACHE=1 proves your caching actually works. Use it.
• Dynamic layouts kill ISR. Keep layouts static if you want the full benefit.