Revalidating Data

Revalidation (also known as Incremental Static Regeneration) allows you to retain the benefits of static while scaling to millions of pages.

There are two types of revalidation in Next.js:

  • Background: Revalidates the data at a specific time interval.
  • On-demand: Revalidates the data based on an event such as an update.

Background Revalidation

To revalidate cached data at a specific interval, you can use the next.revalidate option in fetch() to set the cache lifetime of a resource (in seconds).

fetch('https://...', { next: { revalidate: 60 } });

If you want to revalidate data that does not use fetch (i.e. using an external package or query builder), you can use the route segment config.

app/page.tsx

export const revalidate = 60; // revalidate this page every 60 seconds

In addition to fetch, you can also revalidate data using cache.

How it works

  1. When a request is made to the route that was statically rendered at build time, it will initially show the cached data.
  2. Any requests to the route after the initial request and before 60 seconds are also cached and instantaneous.
  3. After the 60-second window, the next request will still show the cached (stale) data.
  4. Next.js will trigger a regeneration of the data in the background.
  5. Once the route generates successfully, Next.js will invalidate the cache and show the updated route. If the background regeneration fails, the old data would still be unaltered.

When a request is made to a route segment that hasn’t been generated, Next.js will dynamically render the route on the first request. Future requests will serve the static route segments from the cache.

Note: Check if your upstream data provider has caching enabled by default. You might need to disable (e.g. useCdn: false), otherwise a revalidation won't be able to pull fresh data to update the ISR cache. Caching can occur at a CDN (for an endpoint being requested) when it returns the Cache-Control header. ISR on Vercel persists the cache globally and handles rollbacks.

On-demand Revalidation

If you set a 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 if someone visits the page after the minute has passed.

The Next.js App Router supports revalidating content on-demand based on a route or cache tag. This allows you to manually purge the Next.js cache for specific fetches, making it easier to update your site when:

  • Content from your headless CMS is created or updated.
  • Ecommerce metadata changes (price, description, category, reviews, etc).

Using On-Demand Revalidation

Data can be revalidated on-demand by path (revalidatePath) or by cache tag (revalidateTag).

For example, the following fetch adds the cache tag collection:

app/page.tsx

export default async function Page() {
  const res = await fetch('https://...', { next: { tags: ['collection'] } });
  const data = await res.json();
  // ...
}

This cached data can then be revalidated on-demand by calling revalidateTag in a Route Handler.

app/api/revalidate/route.ts

import { NextRequest, NextResponse } from 'next/server';
import { revalidateTag } from 'next/cache';

export async function GET(request: NextRequest) {
  const tag = request.nextUrl.searchParams.get('tag');
  revalidateTag(tag);
  return NextResponse.json({ revalidated: true, now: Date.now() });
}

Error Handling and Revalidation

If an error is thrown while attempting to revalidate data, the last successfully generated data will continue to be served from the cache. On the next subsequent request, Next.js will retry revalidating the data.