Basement.studio가 30개 정적 페이지·약 600개 동적 페이지·15개 언어를 가진 클라이언트 사이트를 Gatsby에서 Next.js로 3주 만에 무중단 마이그레이션한 과정을 기술한다. 빌드 시간 85% 단축(35분 → 5분), Real Experience Score 79 → 90 향상을 달성했으며, 플러그인 중심 Gatsby와 기본 프리미티브 중심 Next.js의 아키텍처 철학 차이를 코드 레벨로 비교한다.
핵심 포인트- Gatsby는 이미지 최적화에 4개 패키지 + 31줄이 필요했지만, Next.js는 `next/image` 단일 import + 7줄로 동일하다. 플러그인 vs 프리미티브 철학의 실질적 차이다.
- 데이터 소스(Ghost, YouTube, GitHub)마다 Gatsby 플러그인이 필요했던 것이 Next.js에서는 getStaticProps 안의 표준 fetch() 호출로 통합된다.
- ISR 하이브리드 전략: 자주 방문하는 페이지는 빌드 타임 정적 생성, 나머지와 다국어 버전은 ISR — 빌드 시간과 성능의 균형점으로 35분 빌드를 5분으로 줄였다.
- Preview Deployments가 마이그레이션 테스트의 핵심이었다 — 페이지별로 점진적 전환 후 프리뷰로 검증, 인프라를 동시에 교체하지 않아 리스크를 낮췄다.
- 3주 무중단: 빌드 85% 단축, Real Experience Score +14%, 코드량 대폭 감소, headless CMS 통합 유지.
상세 정리- 마이그레이션 동기: 기존 Gatsby 구현이 플러그인 의존성, 우회(workaround), 긴 컴파일 주기로 유지보수가 어려워졌다. 개발자 경험 개선과 빌드 시간 단축이 주요 목표였다.
- 대상 규모: 30개 정적 페이지 + 약 600개 동적 페이지 + 15개 언어 번역. 대규모라 점진적 접근이 필수였다.
- 이미지 최적화 비교: Gatsby는 gatsby-plugin-image, gatsby-plugin-sharp, gatsby-source-filesystem, gatsby-transformer-sharp 4개 패키지 + 31줄. Next.js는 next/image 단일 import + 7줄.
- 데이터 패칭 비교: Gatsby는 소스별 플러그인(gatsby-source-ghost, gatsby-source-youtube-v3, gatsby-source-custom-api)으로 각기 다른 API를 써야 했다. Next.js는 getStaticProps 안에서 표준 fetch()로 통일, 소스 무관하게 일관된 패턴이다.
- ISR 하이브리드 전략: 자주 방문하는 페이지는 빌드 타임 정적 생성으로 빠른 응답, 드물게 방문하는 600개 동적 페이지와 다국어 버전은 ISR로 첫 요청 시 생성 후 CDN 캐싱. 빌드 35분 → 5분 달성의 핵심 결정이었다.
- ISR 트레이드오프: "첫 번째 사용자는 오리진 서버 지연이 있지만 이후 사용자는 CDN에서 빠른 응답을 받는다" — 전체 정적 생성 대비 빌드 시간이 획기적으로 줄었다.
- Preview Deployments 활용: 마이그레이션한 페이지마다 프리뷰 URL로 기존과 비교 테스트. 인프라 전환과 코드 마이그레이션을 분리해 점진적으로 진행했다.
- 성능 모니터링: Vercel Analytics와 Checks로 Real Experience Score를 추적해 79 → 90 향상을 수치로 확인했다.
- 아키텍처 철학 차이: Gatsby는 플러그인 생태계로 기능을 확장(높은 추상화, 낮은 제어), Next.js는 기본 프리미티브를 개발자가 직접 활용(낮은 추상화, 높은 제어). 팀 역량과 커스터마이징 필요도에 따라 선택이 달라진다.
- 결과: 3주 내 무중단 완료, 빌드 85% 단축, Real Experience Score +14%, 코드량 대폭 감소, headless CMS(Ghost) 통합 유지.
왜 읽나Gatsby나 다른 정적 사이트 생성기에서 Next.js로 대규모 마이그레이션을 계획하는 팀에게 구체적인 기술 트레이드오프, ISR 전략, 점진적 마이그레이션 방법과 실측 성능 데이터를 제공한다.
Vercel Blog·
LINE Engineering·