Implement Incremental Static Regeneration in Next.js: A Step‑by‑Step Guide

Problem & Desired Outcome

You want your Next.js site to serve statically generated pages that stay fresh without rebuilding the entire application. Incremental Static Regeneration (ISR) lets you update a page in the background after a specified interval, delivering new content to users while keeping the deployment fast.

Prerequisites

• Node.js 18+ and npm or yarn installed.
• A Next.js 13+ project with at least one page that uses getStaticProps.
• Access to a hosting platform that supports ISR (e.g., Vercel, Netlify, or a custom server with Next.js 13+).
• Production build environment (ISR is not active in development mode).

Step‑by‑Step Implementation

1. Add revalidate to getStaticProps

Return a revalidate property (in seconds) from getStaticProps. This tells Next.js to regenerate the page in the background after the specified interval.

export async function getStaticProps() {
  const res = await fetch('https://api.example.com/posts');
  const posts = await res.json();

  return {
    props: { posts },
    revalidate: 10, // seconds
  };
}

Replace the fetch URL and data handling with your own logic. The revalidate value must be a static number; a function or dynamic value is not supported.

2. Build and Run Locally in Production Mode

# Build the application
next build

# Start the production server
next start

Run the above commands in the root of your project. Open http://localhost:3000/your-page to confirm the page renders correctly. Note: ISR will not trigger in this local dev environment; you need a production deployment.

3. Deploy to a Platform that Supports ISR

For Vercel, the simplest method is:

vercel --prod

Follow the prompts to link your project. Vercel automatically detects Next.js and configures the build. After deployment, note the production URL (e.g., https://your-app.vercel.app).

4. Trigger a Page Request to Start the Revalidation Cycle

Access the page in a browser or use curl to record the initial content:

curl -s https://your-app.vercel.app/your-page > before.txt

Wait at least revalidate seconds (10 in the example) and then fetch the page again:

curl -s https://your-app.vercel.app/your-page > after.txt

Compare before.txt and after.txt to verify that the content has changed.

Verifying Revalidation

• Vercel Logs: Run vercel logs --since $(date -d '5 minutes ago' +%s) to look for entries like Revalidating /your-page.
• Network Headers: In the browser dev tools, check the Last‑Modified header or a custom X-Next-ISR-Generated header that Next.js may add.
• Response Status: A successful regeneration returns HTTP 200. If regeneration fails, the cached page is served unchanged.

Recovery & Troubleshooting

• If the page never updates, ensure the deployment platform supports ISR and that the revalidate value is static.
• Check for build errors: a non‑numeric revalidate will abort the build.
• High traffic can cause queued regenerations; monitor the logs for Regeneration queued messages.
• When regeneration fails (e.g., network error), the previous static page remains. Inspect the error in the logs and fix the data source or fallback logic.

Limitations & Best Practices

• ISR only works with getStaticProps. It cannot be combined with getServerSideProps or client‑side fetching for the same page.
• Dynamic revalidate values (based on runtime data) are not supported; keep the value deterministic.
• In development mode (next dev), ISR is disabled. Test revalidation only after a production build.
• Consider setting a reasonable revalidate interval: too short may overload the server, too long may serve stale data.
• Use a CDN cache‑busting strategy if your hosting platform does not automatically invalidate cached assets after regeneration.

Practical Check

After deployment, run the following script to automatically verify that ISR updates the page:

node - <<'NODE'
const https = require('https');
const url = 'https://your-app.vercel.app/your-page';

function fetchPage() {
  return new Promise((resolve, reject) => {
    https.get(url, res => {
      let data = '';
      res.on('data', chunk => data += chunk);
      res.on('end', () => resolve(data));
    }).on('error', reject);
  });
}
(async () => {
  const before = await fetchPage();
  console.log('First fetch:', before.slice(0, 50));
  console.log('Waiting 15 seconds…');
  await new Promise(r => setTimeout(r, 15000));
  const after = await fetchPage();
  console.log('After fetch:', after.slice(0, 50));
  console.log('Content changed:', before !== after);
})();
NODE

Replace https://your-app.vercel.app/your-page with your actual URL. The script prints a snippet of the page before and after the revalidation interval and reports whether the content changed.