ISR (Incremental Static Regeneration)

What ISR Is

Incremental Static Regeneration (ISR) is a rendering strategy that pre-generates HTML like SSG but also refreshes pages in the background after TTL expiry. The term was coined by Next.js 9.5 (2020); similar features have since spread across frameworks — Nuxt / Nitro's `swr`, SvelteKit's `isr`, etc. The official Next.js docs describe ISR's behavior as follows:

Incremental Static Regeneration (ISR) enables you to:

• Update static content without rebuilding the entire site
• Reduce server load by serving prerendered, static pages for most requests
• Ensure proper cache-control headers are automatically added to pages
• Handle large amounts of content pages without long next build times

— Next.js Documentation (MIT)

In other words, ISR sits between pure SSG ('rebuild the whole site for every update') and SSR ('re-render on every request'). It behaves like SSG most of the time (CDN-served, near-zero server load) while regenerating selectively when needed — a hybrid strategy.

Rendering Lifecycle

The build-time phases (B1-B3) are identical to SSG. ISR's essence lives at runtime: within TTL the CDN serves static HTML instantly; after TTL expires, the first request triggers stale-while-revalidate behavior — serving stale content immediately while regenerating in the background (R3-R6). The on-demand path (R7) lets a webhook invalidate any path on the spot.

Next.js ISR (Key APIs)

Since 'ISR' is the name Next.js coined, its APIs provide the most systematic coverage. Here are the key declarations and operational headers.

export const revalidate = 60

Enables time-based revalidation on a per-page basis. 60-second TTL. The most basic ISR declaration — also the form used in Next.js's minimal example.

revalidatePath('/blog/1')

On-demand revalidation by path. Call from a Server Action or Route Handler to invalidate that path's cache. Next.js recommends 'For most use cases, prefer revalidating entire paths.'

revalidateTag('posts')

On-demand revalidation by tag. Invalidates all caches associated with a tag that was attached at fetch time via next: { tags: ['posts'] }. For finer-grained control.

x-nextjs-cache: HIT / STALE / MISS / REVALIDATED

Response header attached by Next.js indicating cache state. HIT = served from cache, STALE = served from cache while revalidating in background, MISS = not in cache, rendered fresh, REVALIDATED = regenerated via on-demand revalidation. Essential for operational debugging.

Equivalent Features in Other Frameworks

The name 'ISR' is Next.js-specific, but the same concept (static generation + background regeneration = HTTP's stale-while-revalidate) is available across major frameworks with different terminology and syntax. Here's the support landscape.

// nuxt.config.ts
export default defineNuxtConfig({
  routeRules: {
    '/blog/**': { swr: 600 },        // 600s TTL
    '/static/**': { isr: 3600 },     // ISR で 1 時間キャッシュ
    '/admin/**': { ssr: false },     // SPA モード
  },
})

// +page.js (or +page.server.js)
export const config = {
  isr: {
    expiration: 60,
    bypassToken: BYPASS_TOKEN,  // 32 文字以上
    allowQuery: ['search']
  }
};

// Astro の on-demand page
export const prerender = false;
// ---
// <script> 的な部分で:
Astro.response.headers.set(
  'Cache-Control',
  'public, max-age=3600, stale-while-revalidate=60'
);

// loader.ts
export const loader = async () => {
  return new Response(JSON.stringify(data), {
    headers: {
      'Cache-Control':
        'public, s-maxage=60, stale-while-revalidate=600',
    },
  });
};

Frequently Asked Questions

Clarifying the positions of ISR / SSG / SSR and the operational quirks that tend to surprise people.

Design Signals

When ISR is the right choice — and when another strategy is cleaner.

Common Pitfalls