Next.js Releases On-demand Incremental Static Regeneration

Introduction

I wrote an article about Data Fetching in Nextjs ; in it I talked about the different way data is fetched and rendered in Next.js. I explained how Incremental Static Regeneration is what happens when you add revalidate to getStaticProps.

What Does ISR Currently Do

Currently when you want to use Incremental Static Regeneration, you employ a revalidate parameter in your return statement.

// This function gets called at build time on server-side.
// It may be called again, on a serverless function, if
// revalidation is enabled and a new request comes in
export async function getStaticProps() {
  const res = await fetch('https://.../posts')
  const posts = await res.json()

  return {
    props: {
      posts,
    },
    // Next.js will attempt to re-generate the page:
    // - When a request comes in
    // - At most once every 60 seconds
    revalidate: 60, // In seconds
  }
}

At build time, all pages are generated and rendered.

When a request is made to a pre-rendered page, the cached page is shown.

Any requests to the page before the 60 seconds will instantaneously show the cached page.

When a request is made after the 60 seconds, the page is regenerated in the background. When that has succeeded, the cached version is discarded (invalidated) and the updated page is shown; becoming the new cache.

With revalidate set to 60, all visitors will see the generated version of your site for 60 seconds.

This will soon be a thing of the past.

What Will This Feature Introduce?

From Next.js v12.1.0, you will now have access to the unstable_revalidate() function. This will allow revalidation of pages that use getStaticProps. This is referred to as On-demand Incremental Static Regeneration.

In essence, you have the ability to manually purge the Next.js cache, making it easier to update your site when the data that fuels it changes.

You won't need to add revalidate to getStaticProps when using this feature.

How To Use On-demand Incremental Static Regeneration

Let's take a look at how you make use of On-demand Incremental Static Regeneration in your Next app.

Create a secret token only known by your next app

Add the token to your Environment Variables
```
SECRET_TOKEN=''
```
Create the revalidation API route

// 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.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')
  }
}

And there you have it. Your pages regenerate automatically.

Conclusion

I am so excited about this new feature. I have been racking my brain as to what is a sensible revalidate time - it being in seconds wasn't helping at all.

Update: 20 February 2022

I had some questions after I read the docs, so I reached out to Lee Robinson

For the token, a jwt one will work?

Yes you can use any kind of token to secure the route.
Am I able to pass more that I one path to this?
await res.unstable_revalidate('/path-to-revalidate')

You can only currently revalidate a single path at once.

Thank you for reading, let's connect!

Thank you for visiting this little corner of mine. Let's connect on Twitter, Polywork and LinkedIn