HashiCorp 개발자가 ISR로 개발 반복 속도를 높인 방법

Next.js의 ISR(Incremental Static Regeneration)은 전체 사이트 재빌드 없이 개별 페이지를 런타임에 재생성하는 렌더링 전략이다. HashiCorp의 8개 제품 문서 사이트를 관리하는 시니어 웹 엔지니어 Bryce Kalow가 실제 도입 사례를 공유했다. Next.js 12.1에서 도입된 온디맨드 ISR은 CMS 웹훅이나 GitHub 이벤트를 받아 특정 페이지 캐시만 즉시 무효화해, 변경된 페이지만 재생성하는 효율적인 콘텐츠 업데이트 아키텍처를 가능하게 한다.

핵심 포인트

기존 SSG: 모든 변경에 전체 사이트 재빌드 필요. 페이지 수에 비례해 빌드 시간 선형 증가
ISR: `getStaticProps`의 `revalidate` 값 만료 시 백그라운드에서 페이지 재생성 (Stale-While-Revalidate)
`fallback: 'blocking'`: 빌드 시 생성하지 않은 페이지도 첫 방문 시 온디맨드로 정적 생성 후 캐싱
온디맨드 ISR: `/api/revalidate` 엔드포인트로 특정 경로의 Next.js 캐시 즉시 무효화
HashiCorp는 애널리틱스 기반 상위 페이지만 빌드 시 정적 생성, 나머지는 `fallback: 'blocking'` 처리
GitHub Actions → 변경된 파일 diff → 변경된 페이지만 온디맨드 ISR 호출로 불필요한 전체 재빌드 제거

상세 정리

**ISR 기본 원리**: `getStaticProps`에서 `revalidate: 360` (초) 설정 시 1시간 후 만료. 다음 요청 시 백그라운드에서 재생성하며 사용자는 재생성 중에도 캐시된 이전 버전을 받음
**HashiCorp 규모**: 8개 오픈소스 제품(Terraform, Vault 등) 각각의 버전별 문서 사이트. 버전별 문서 추가로 페이지 수 급증 → 전체 재빌드 비현실적
**애널리틱스 기반 정적 생성**: `getStaticPaths`에서 `getTopPathsFromAnalytics(ctx)` 호출로 트래픽 상위 페이지만 빌드 시 생성, 나머지는 `fallback: 'blocking'` 으로 첫 방문 시 생성
**온디맨드 ISR 엔드포인트**: 시크릿 토큰 검증 후 `response.unstable_revalidate(path)` 호출로 특정 경로의 Next.js 캐시 즉시 무효화. 변경된 경로만 타겟
**GitHub Actions 통합**: GitHub 앱이 push 이벤트 감지 → 변경된 파일 diff 분석 → 변경된 문서 경로에만 온디맨드 ISR 호출. 전체 배포 없이 콘텐츠 업데이트 완료
**기존 deploy hook 병행 유지**: 제품 출시 같은 대량 변경에는 전체 배포 hook 유지, 소규모 변경에는 온디맨드 ISR 사용으로 불필요한 재빌드 최소화
**캐싱 전략 튜닝**: 온디맨드 ISR이 있으면 `revalidate` 타이머를 길게 설정해도 안전 — 즉시 무효화가 보장되므로 캐시 효율 증가 가능
**콘텐츠-API 분리**: 파일시스템에서 직접 읽던 방식 → API에서 콘텐츠 제공 방식으로 전환. ISR과 결합해 빌드 독립적인 콘텐츠 업데이트 가능
**엣지 컴퓨팅 탐색**: HashiCorp는 Next.js Middleware를 엣지 테스트베드로 활용 중, 정적 생성 이점 유지하면서 엣지로 이전 가능한 기능 탐색

왜 읽나CMS 웹훅·GitHub Actions와 온디맨드 ISR을 연결해 "변경된 페이지만 즉시 재생성"하는 아키텍처를 실제 코드로 확인할 수 있어, 대규모 정적 사이트의 콘텐츠 신선도 문제를 해결하는 실전 패턴을 제공한다.

Vercel Blog 블로그

원문은 여기서 이어서 읽을 수 있어요

원문 읽기

읽음 (0)

·takedown 요청

HashiCorp 개발자가 ISR로 개발 반복 속도를 높인 방법

이 글과 비슷한

Chat SDK의 Discord Components V2 지원 추가

Flags SDK, 플래그 평가 속도 10배 개선

AI로 웹 엔지니어 없이 LINE 앱 안에서 그룹 영상 통화 서비스 만들기