Skip to content

The following examples show how to use ISR with Next.js or the Build Output API, either in the background or on-demand.

This example shows how to create a Next.js page with a dynamic route that uses Incremental Static Regeneration. getStaticProps will be turned into an ISR Render Function (Serverless) when deployed to Vercel.

Try it out by:

  • Create a new file pages/posts/[id].js and copy the contents below
  • Navigate to localhost:3000/posts/1

You should see Hello World! displayed in the browser.

pages/posts/[id].js
export default function Page({ posts }) {
  return posts[0].title;
}

export async function getStaticProps() {
  return {
    props: {
      posts: [
        {
          title: 'Hello World!',
        },
      ],
    },
    revalidate: 10, // In seconds
  };
}

export async function getStaticPaths() {
  return {
    paths: [
      {
        params: { id: '1' },
      },
    ],
    fallback: 'blocking',
  };
}

To learn more about ISR usage in Next.js, check out the documentation.

If you set a background revalidate time of 60, all visitors will see the same generated version of your site for one minute. The only way to invalidate the cache is by someone visiting that page after the minute has passed. On-demand revalidation allows you to purge the cache globally using an API Route.

This examples build off the above background example to also regenerate the page on-demand using an API Route.

Try it out by:

  • Copy the steps from the background example
  • Create a secret token to prevent unauthorized access to the revalidation API Route
  • Add the secret value as an Environment Variable
  • Create a new API Route (pages/api/revalidate.js) and copy the contents below
  • Navigate to localhost:3000/api/revalidate?secret=<your-token> to re-run getStaticProps
pages/api/revalidate.js
export default async function handler(req, res) {
  // Check for secret to confirm this is a valid request
  if (req.query.secret !== process.env.MY_SECRET_TOKEN) {
    return res.status(401).json({ message: 'Invalid token' });
  }

  try {
    await res.revalidate('/post/1');
    return res.json({ revalidated: true });
  } catch (err) {
    // If there was an error, Next.js will continue
    // to show the last successfully generated page
    return res.status(500).send('Error revalidating');
  }
}
Note: You do not need to specify revalidate inside getStaticProps to use on-demand revalidation. If revalidate is omitted, Next.js will use the default value of false (no revalidation) and only revalidate the page on-demand when res.revalidate is called.

Try out a demo of on-demand revalidation or view the source code. To learn more about ISR usage in Next.js, check out the documentation.

Incremental Static Regeneration works well for ecommerce, marketing pages, blog posts, ad-backed media, and more.

  • On-Demand ISR Demo – Create or comment on a GitHub issue to see pages update globally, instantly.
  • Ecommerce Demo – Next.js Commerce is an all-in-one starter kit for high-performance e-commerce sites.
  • GitHub Reactions Demo – React to the original GitHub issue and watch ISR update the statically generated landing page.
  • Static Tweets Demo – This project deploys in 30 seconds, but can statically generate 500M tweets on-demand using ISR.