What is Next.js On-demand Incremental Static Regeneration and How to Use it?

Table of Content

What is On-demand Incremental Static Regeneration in Next.js?
Why is On-demand Incremental Static Regeneration Better than Incremental Static Regeneration?
Difference between On-demand Incremental Static Regeneration and Incremental Static Regeneration
How to use On-demand Incremental Static Regeneration in Next.js?
Wrap Off

Next.js Incremental Static Regeneration has been one of the features that got me hooked to Next.js.

A year ago, Next.js 9.3, released support for Static Site Generation (SSG) making it the first hybrid framework.

Until recently, they were only two ways to carry out data fetching in Next.js: static site generation (SSG) and server-side rendering (SSR).

But Next.js v9.5 introduced a new data fetching strategy called Incremental Static Regeneration (ISR), a hybrid version of the two.

When I first used it, I had a “Yes! This is the bomb!” moment.

Not only do I appreciate Next.js Incremental Static Regeneration for the significant reduction in build time, but also the ability to build a static site without the sacrifice of stale content.

You may not understand why ISR is a big deal until you have to build a large project with a lot of pages and constantly changing data without sacrificing performance and SEO, such as an eCommerce.

In this post, you will learn about Next.js On-demand Incremental Static Regeneration and how to use it.

What is On-demand Incremental Static Regeneration in Next.js?

On-demand Incremental Static Regeneration is an addition to the Next.js ISR that allows you to build real-time static websites that are dynamic as well as change in real-time.

These changes are statically-generated in the background leading to you getting the benefit of both &mdaash; Static-site Generation and Server-side Rendering — a faster page load and globally updated data.

Why is On-demand Incremental Static Regeneration Better than Incremental Static Regeneration?

You might be wondering why on-demand incremental static regeneration is better than regular incremental static regeneration.

With ISR, static pages can be generated at runtime (on-demand) rather than at build-time.

When data changes, the changes to the page are resolved when the revalidate period expires.

After the revalidate period, the first visit to the page revalidates, and the completed page is cached.

However, the visitor responsible for the revalidation still gets the stale data, the visitor receives the cached version first. Subsequent users to that page will be served the new cached version immediately.

But that is not available to the visitor who revalidates the page. To get the updated version, the visitor has to hard-reload the page.

To mitigate this, some developers set a short revalidation period of about 60 seconds. However, even that has its issues.

For example, it might not be feasible for an eCommerce in an event like Black Friday when prices are constantly changing.

Hence, there has been a demand for interval-based revalidations and the need to provide more flexibility.

Here comes on-demand incremental static regeneration.

On-demand incremental static regeneration allows you to manually purge the Next.js cache for a specific page on-demand.

This means that rather than wait for a user to visit the page and revalidate it, you can set it in a way that the page changes demanded while still being static and served via CDN.

Isn’t that incredible!

This makes it easier to update your site when content from a headless CMS or backend API is created or updated, and when eCommerce metadata such as price, description, category, reviews, etc., changes.

Difference between On-demand Incremental Static Regeneration and Incremental Static Regeneration

Now you’ve seen why on-demand incremental static regeneration is better than regular incremental static regeneration.

Here are the differences between the two:

In the regular incremental static regeneration, you need to specify a revalidate period for the page to be regenerated. However, in on-demand incremental static regeneration, you do not need to specify revalidate.
In the regular incremental static regeneration, the only way to invalidate the cache was from someone visiting that page after the specified revalidation period. You can now manually purge the Next.js cache for a specific page on-demand.

How to use On-demand Incremental Static Regeneration in Next.js?

As of the time of writing this article, on-demand incremental static regeneration is in beta mode and available from Next.js version 12.1.

Here is how you can use the Next.js on-demand incremental static regeneration:

Start a new project or update an existing project to Next.js version 12.1 and above.
Create a getStaticProps function as you normally would.

Inside getStaticProps, you do not need to specify revalidate.

Create a new endpoint in pages/api. Inside the file, create an async handler function whose response calls the unstable_revalidate function. The parameter of the unstable_revalidate is the URL of the API endpoint you want to revalidate.

await res.unstable_revalidate('/path-to-revalidate')

Highlighted code sample.

Below is a code example of the handler function from Next.js example of how to use it:


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.unstable_revalidate('/path-to-revalidate')
    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')
  }
}

Highlighted code sample.

And that’s it. That’s all you have to do.

Wrap Off

This post was meant to be candid and not deep dive into the technical use case for on-demand incremental static regeneration.

I hope you learned something substantial.

I’ll be making a post on how to build a project with it and a better example.

Kindly subscribe to my newsletter, so you will be informed when that happens.