Getting Started

Getting started with ISR

This guide will help you get started with using Incremental Static Regeneration (ISR) on your project, showing you how to regenerate your pages without rebuilding and redeploying your site. When a page with ISR enabled is regenerated, the most recent data for that page is fetched, and its cache is updated. There are two ways to trigger regeneration:

Background revalidation – Regeneration that recurs on an interval
On-demand revalidation – Regeneration that occurs when you send certain API requests to your app

Background Revalidation

Background revalidation allows you to purge the cache for an ISR route automatically on an interval.

When using Next.js with the App Router, you can enable ISR by using the revalidate route segment config for a layout or page.

apps/example/page.tsx

export const revalidate = 10; // seconds

Example

The following example renders a list of blog posts from a demo site called jsonplaceholder, revalidating every 10 seconds or whenever a person visits the page:

app/blog-posts/page.tsx

export const revalidate = 10; // seconds
 
interface Post {
  title: string;
  id: number;
}
 
export default async function Page() {
  const res = await fetch('https://api.vercel.app/blog');
  const posts = (await res.json()) as Post[];
  return (
    <ul>
      {posts.map((post: Post) => {
        return <li key={post.id}>{post.title}</li>;
      })}
    </ul>
  );
}

To test this code, run the appropriate dev command for your framework, and navigate to the /blog-posts/ route.

You should see a bulleted list of blog posts.

On-Demand Revalidation

On-demand revalidation allows you to purge the cache for an ISR route whenever you want, foregoing the time interval required with background revalidation.

To revalidate a page on demand with Next.js:

Create an Environment Variable which will store a revalidation secret
Create an API Route that checks for the secret, then triggers revalidation

The following example demonstrates an API route that triggers revalidation if the query paramater ?secret matches a secret Environment Variable:

app/api/revalidate/route.ts

import { revalidatePath } from 'next/cache';
 
export async function GET(request: Request) {
  const { searchParams } = new URL(request.url);
  if (searchParams?.secret !== process.env.MY_SECRET_TOKEN) {
    return new Response(`Invalid credentials`, {
      status: 500,
    });
  }
  revalidatePath('/blog-posts');
  return new Response(
    {
      revalidated: true,
      now: Date.now(),
    },
    {
      status: 200,
    },
  );
}