Recapping ISR: The "Stale-While-Revalidate" Strategy

Incremental Static Regeneration (ISR) is a genius solution to a common problem: how do you keep a static site updated without rebuilding the entire thing?

Here's how it works:

  1. Initial Build: The page is generated statically at build time (like SSG) and served instantly from the CDN.
  2. Stale Period: You define a revalidate time (e.g., 60 seconds). For the next 60 seconds, all users will receive the same cached, stale page.
  3. Revalidation: After 60 seconds, the next user who requests the page will still get the stale page instantly. But in the background, Next.js triggers a regeneration of the page with fresh data.
  4. Cache Update: Once the new page is built, Next.js silently updates the cache. Everyone who visits from that point on gets the new version, until the next revalidation period ends.

This "stale-while-revalidate" approach ensures users always have a fast experience, while the content stays reasonably fresh.

Use Case 1: E-commerce Product Page

An e-commerce page is a perfect candidate for ISR.

  • The Content: The product title, description, and images are mostly static.
  • The Problem: The price or stock level might change.
  • The ISR Solution: Statically generate the page at build time. Set a revalidation period of, say, 5 minutes (revalidate: 300). This gives you static speed, but ensures price and stock information are never more than 5 minutes out of date.

JavaScript


// app/products/[id]/page.js
async function getProduct(id) {
  const res = await fetch(`https://api.mystore.com/products/${id}`, {
    next: { revalidate: 300 } // Revalidate every 5 minutes
  });
  return res.json();
}

Use Case 2: Blog or News Article

A blog post seems perfectly static, but what if you find a typo or want to add an update?

  • The Content: The article itself.
  • The Problem: You don't want to redeploy your entire site just to fix a small mistake.
  • The ISR Solution: Use ISR with a longer revalidation time (e.g., 1 hour) or, even better, use On-Demand Revalidation.

On-Demand Revalidation

This is a powerful feature that lets you manually trigger a page regeneration. You can set up a webhook in your Content Management System (CMS) so that whenever you hit "Publish" or "Update" on a post, it calls a special API route in your Next.js app. This route then tells Next.js to revalidate that specific page immediately.

JavaScript


// app/api/revalidate/route.js
import { revalidateTag } from 'next/cache'
import { NextResponse } from 'next/server'

export async function POST(request) {
  const tag = request.nextUrl.searchParams.get('tag')

  if (!tag) {
    return NextResponse.json({ message: 'Missing tag param' }, { status: 400 })
  }

  // Tells Next.js to revalidate any fetch requests that used this tag
  revalidateTag(tag)

  return NextResponse.json({ revalidated: true, now: Date.now() })
}

You would then "tag" your data fetches: fetch('...', { next: { tags: ['posts'] } })

Use Case 3: A Popular Social Media Profile

Imagine a profile page for a popular creator.

  • The Content: Bio, profile picture, list of recent posts.
  • The Problem: The page is viewed thousands of times per minute. Server-rendering it for every single user would be incredibly expensive and slow.
  • The ISR Solution: Use ISR to revalidate the page every minute. 99% of users will get a super-fast static page, while the content is never more than 60 seconds old.