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

id, title, category, status, canonical_id, aliases, duplicate_of, source_trust_level, confidence_score, verification_status, tags, raw_sources, last_reinforced, github_commit, tech_stack

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

// 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

// 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)

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)

// 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

// 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)

// 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