2nd/10_Wiki/Topics/Architecture/Incremental-Static-Regeneration-ISR.md

---
id: wiki-2026-0508-incremental-static-regeneration-
title: Incremental Static Regeneration (ISR)
category: 10_Wiki/Topics
status: verified
canonical_id: self
aliases: [ISR, Stale-While-Revalidate Static, On-Demand Revalidation]
duplicate_of: none
source_trust_level: A
confidence_score: 0.9
verification_status: applied
tags: [architecture, nextjs, ssg, caching, web]
raw_sources: []
last_reinforced: 2026-05-10
github_commit: pending
tech_stack:
  language: typescript
  framework: nextjs
---

# Incremental Static Regeneration (ISR)

## 매 한 줄
> **"매 static page 의 build-time 의 prerender + runtime 의 stale-while-revalidate 의 통한 fresh 의 hybrid"**. 매 Next.js 9.5 (2020) 의 introduction, 매 Vercel 의 patent (US 11,055,090), 매 modern 의 Next.js 15 App Router 의 `revalidate` + `revalidateTag` + `revalidatePath` 의 first-class.

## 매 핵심

### 매 ISR 동작
1. Build 시 page 의 prerender → static HTML + JSON.
2. Request 의 cached HTML 의 즉시 serve.
3. `revalidate: N` 초 후 첫 request 의 background regenerate trigger.
4. 매 그 request 는 stale 의 받음, 매 다음 request 는 fresh.
5. On-demand: webhook → `revalidateTag('post-123')` 의 cache 의 invalidate.

### 매 ISR vs SSR vs SSG
- **SSG**: build-time only, content change → rebuild.
- **SSR**: every request, fresh but slow + costly.
- **ISR**: prerendered + revalidate window, near-CDN speed + freshness.
- **PPR (Partial Prerendering, Next.js 15)**: static shell + dynamic holes — ISR 의 evolution.

### 매 응용
1. Marketing/blog (수십만 page).
2. E-commerce product page (price/stock 의 stale OK seconds).
3. Docs site (authored content, low write rate).

## 💻 패턴

### App Router — Time-Based Revalidate
```typescript
// app/blog/[slug]/page.tsx
export const revalidate = 60; // seconds

export default async function Post({ params }: { params: { slug: string } }) {
  const post = await fetch(`https://cms.example.com/posts/${params.slug}`, {
    next: { revalidate: 60, tags: [`post:${params.slug}`] },
  }).then(r => r.json());

  return <article>{post.title}</article>;
}

export async function generateStaticParams() {
  const posts = await fetch('https://cms.example.com/posts').then(r => r.json());
  return posts.map((p: any) => ({ slug: p.slug }));
}
```

### On-Demand — `revalidateTag`
```typescript
// app/api/revalidate/route.ts
import { revalidateTag } from 'next/cache';
import { NextRequest } from 'next/server';

export async function POST(req: NextRequest) {
  const secret = req.headers.get('x-webhook-secret');
  if (secret !== process.env.WEBHOOK_SECRET) {
    return new Response('forbidden', { status: 403 });
  }
  const { slug } = await req.json();
  revalidateTag(`post:${slug}`);
  return Response.json({ revalidated: true, slug });
}
```

### `revalidatePath` (entire route)
```typescript
import { revalidatePath } from 'next/cache';

export async function publishPost(slug: string) {
  await db.posts.update({ where: { slug }, data: { published: true } });
  revalidatePath(`/blog/${slug}`);
  revalidatePath('/blog');
}
```

### Pages Router (legacy `getStaticProps`)
```typescript
// pages/products/[id].tsx
export async function getStaticProps({ params }) {
  const product = await fetch(`/api/products/${params.id}`).then(r => r.json());
  return { props: { product }, revalidate: 30 };
}

export async function getStaticPaths() {
  const top100 = await fetch('/api/products?top=100').then(r => r.json());
  return {
    paths: top100.map((p: any) => ({ params: { id: p.id } })),
    fallback: 'blocking', // first request 의 SSR-then-cache
  };
}
```

### CMS Webhook → ISR
```typescript
// Sanity / Contentful / Strapi webhook
{
  "url": "https://app.example.com/api/revalidate",
  "headers": { "x-webhook-secret": "..." },
  "events": ["entry.publish", "entry.update"]
}
```

### Partial Prerendering (Next.js 15)
```typescript
// next.config.ts
export default { experimental: { ppr: 'incremental' } };

// app/page.tsx
export const experimental_ppr = true;
import { Suspense } from 'react';

export default function Page() {
  return (
    <>
      <StaticHero />               {/* prerendered */}
      <Suspense fallback={<Skel/>}>
        <DynamicCart />            {/* streamed at request time */}
      </Suspense>
    </>
  );
}
```

## 매 결정 기준
| 상황 | Approach |
|---|---|
| Content-heavy, low write | ISR + on-demand revalidate |
| Per-user dashboard | SSR / Server Components (no ISR) |
| Pure static (마케팅 사이트) | SSG, no revalidate |
| Real-time (stock ticker) | Streaming / WebSocket |
| Mixed page (static + dynamic) | PPR (Next.js 15+) |

**기본값**: 매 content site — App Router + tag-based on-demand revalidation, 매 fallback 의 time-based 60s.

## 🔗 Graph
- 부모: [[Web-Rendering-Strategies]]
- 변형: [[Stale-While-Revalidate]] · [[Edge-SSR]]
- 응용: [[Next.js]]
- Adjacent: [[CDN]] · [[React Server Components — 경계 의식]] · [[Island Architecture]]

## 🤖 LLM 활용
**언제**: revalidate strategy 의 design, webhook handler 의 generate, cache tag 의 schema 의 propose.
**언제 X**: 매 personalized content 의 cache key 의 design (PII leak risk — human review 필수).

## ❌ 안티패턴
- **Per-user ISR**: cookie/auth-dependent page 의 ISR → cross-user data leak.
- **Tag explosion**: 매 query 의 unique tag → 매 cache 의 fragmentation.
- **No fallback**: `fallback: false` + dynamic params → 404 의 surprise.
- **Webhook 의 unsecured**: secret 의 X → revalidate 의 abuse 의 origin DoS.
- **Long `revalidate`**: 1-day window 의 stale price → 매 revenue loss.

## 🧪 검증 / 중복
- Verified (Next.js 15 docs, Vercel ISR blog 2020-2025).
- 신뢰도 A.

## 🕓 Changelog
| 날짜 | 변경 |
|---|---|
| 2026-05-08 | Phase 1 |
| 2026-05-10 | Manual cleanup — Next.js ISR 의 full content |