ISR (Incremental Static Regeneration)

ISR の概論

ISR (Incremental Static Regeneration) は「SSG の静的生成を基本としつつ、期限切れ後にバックグラウンドで HTML を再生成する」レンダリング戦略。Next.js 9.5 (2020) で「Incremental Static Regeneration」として命名され、以降 Nuxt / Nitro の swr、SvelteKit の isr 等、他フレームワークでも類似機能が広がった。Next.js 公式ドキュメントでは ISR の動作を次のように説明している:

ISR (Incremental Static Regeneration) を使うと次のことが可能になります:

• サイト全体を再ビルドせずに静的コンテンツを更新できる
• 大半のリクエストに対して事前レンダリングされた静的ページを配信することで、サーバー負荷を軽減できる
• 適切な cache-control ヘッダーがページに自動的に付与される
• next build の実行時間を長くすることなく、大量のコンテンツページを扱える

— Next.js Documentation (MIT) より。英語原文をサイト独自に和訳。

つまり ISR は、純粋な SSG の「更新のたびに全サイト再ビルド」と、SSR の「毎リクエスト再レンダリング」のちょうど中間にある。普段は SSG 寄りの挙動 (CDN 配信でサーバー負荷極小) を取りながら、必要なときだけ部分的に再生成する、というハイブリッド戦略。

レンダリングライフサイクル

ビルド時のフェーズは SSG と完全に同じ (B1-B3)。ISR の真骨頂はランタイムで、期限内は CDN から static HTML を即返却、期限切れ後の最初のアクセスで「stale を即返却 + バックグラウンド再生成」の stale-while-revalidate 挙動が発動する (R3-R6)。on-demand 系 (R7) は webhook 起点で任意のパスをその場で無効化できる。

Next.js ISR (主要 API)

「ISR」という用語は Next.js が命名した機能名なので、本家の API が最も体系的に整っている。主要な指定方法と運用上のヘッダーを整理する。

export const revalidate = 60

ページ単位で time-based revalidation を有効化。60 秒の TTL。Next.js 公式の最小例でも使われる最も基本的な ISR 指定。

revalidatePath('/blog/1')

on-demand revalidation (パス指定)。Server Action や Route Handler から呼び出して、そのパスの cache を無効化。Next.js 公式の推奨は「ほとんどのユースケースではパス全体の revalidate を優先せよ」。

revalidateTag('posts')

on-demand revalidation (タグ指定)。fetch 時に next: { tags: ['posts'] } で付けたタグに紐付くキャッシュ全てを無効化。より細粒度なコントロール用。

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

Next.js がレスポンスに付けるキャッシュ状態ヘッダー。HIT = キャッシュから提供、STALE = キャッシュから提供しつつバックグラウンド再生成中、MISS = キャッシュに無く都度生成、REVALIDATED = on-demand で再生成された。運用時のデバッグに必須。

他フレームワークの ISR 相当機能

「ISR」という名前は Next.js 固有だが、同じ概念 (静的生成 + バックグラウンド再生成 = HTTP の stale-while-revalidate) は主要フレームワークで利用可能。用語と設定方法が異なるだけ。以下、各フレームワークの対応状況。

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

よくある疑問

ISR / SSG / SSR の位置関係や、運用上ハマりやすい挙動を整理。

設計判断のサイン

ISR を採用すべきケースと、他の戦略のほうが素直なケース。

よくある落とし穴