Gatsby를 Next.js로 마이그레이션

Gatsby 사이트가 Next.js로 이전하는 이유

Gatsby는 정적 사이트 생성이 유일한 실질적 선택지였을 때는 좋은 선택이었습니다. 하지만 웹은 진화했고, Gatsby는 따라가지 못했습니다. 당신의 사이트는 빌드 타임 렌더링에만 갇혀있고, 아마 필요하지도 않은 GraphQL 데이터 레이어에 얽혀있으며, 콘텐츠가 늘어날수록 악화되는 빌드 시간으로 고통받고 있습니다.

Next.js는 Gatsby가 하는 모든 것 — 정적 생성, React 컴포넌트, 파일 기반 라우팅 — 을 제공할 뿐만 아니라 서버 사이드 렌더링, 증분 정적 재생성(ISR), API 라우트, 미들웨어를 추가로 제공합니다. 동일한 React 생태계, 제약은 없습니다.

두 프레임워크 모두 React 기반이므로, 실제 컴포넌트는 거의 변경되지 않습니다. 마이그레이션은 주로 데이터 페칭 패턴과 라우팅에 관한 것입니다. UI를 다시 작성할 필요가 없습니다.

Gatsby의 실제 문제점

모든 것을 위한 GraphQL은 과도합니다

Gatsby는 모든 데이터 상호작용을 GraphQL을 통해 라우팅합니다. CMS에서 블로그 게시물 목록을 가져오고 싶으신가요? GraphQL 쿼리입니다. 사이트 메타데이터가 필요하신가요? GraphQL 쿼리입니다. JSON 파일을 읽고 싶으신가요? GraphQL 쿼리입니다. 이것은 2018년에는 영리했습니다. 이제는 단지 마찰일 뿐입니다.

createPages 로직으로 가득 찬 gatsby-node.js 파일을 유지하고, 페이지 쿼리, 정적 쿼리, 단순한 fetch() 호출이어야 할 것을 위한 프래그먼트 정의를 작성합니다. 팀의 모든 신입 개발자는 의미 있는 것을 기여하기 전에 Gatsby의 GraphQL 컨벤션을 배워야 합니다.

확장성이 떨어지는 빌드 시간

Gatsby는 빌드 타임에 모든 것을 다시 빌드합니다. 500페이지 사이트는 5-10분 정도 걸릴 수 있습니다. 5,000페이지 사이트라면? 20-45분을 봐야 합니다. 모든 콘텐츠 업데이트는 전체 리빌드를 트리거합니다. 마케팅 팀은 블로그 게시물이 라이브되는 것을 보기 위해 30분을 기다립니다.

Incremental Static Regeneration(ISR)을 사용한 Next.js는 이 문제를 완전히 해결합니다. 페이지는 정의한 일정에 따라 백그라운드에서 재생성됩니다. 새로운 콘텐츠는 몇 분이 아닌 몇 초 내에 나타납니다.

플러그인 의존성 지옥

Gatsby의 플러그인 생태계는 한때 가장 큰 판매 포인트였습니다. 이제는 책임입니다. 플러그인은 주요 버전 업그레이드 시 손상됩니다. 일부는 포기되었습니다. 이미지 최적화, CSS 처리, 글꼴 로딩, 메타데이터 관리 — Next.js가 기본적으로 제공하는 것을 달성하기 위해 gatsby-plugin-* 의존성 3단계 깊이에 있습니다.

업데이트 후 gatsby-plugin-image가 손상되고 밤 11시에 소스 맵을 디버깅하고 있다면, 그것이 팀이 마이그레이션하기로 결정하는 순간입니다.

서버 사이드 렌더링 없음

Gatsby는 정적 전용입니다. 인증된 페이지가 필요하신가요? 로딩 스피너가 있는 클라이언트 측 렌더링입니다. 실시간 데이터가 필요하신가요? 하이드레이션 후 클라이언트 측 페칭입니다. 개인화가 필요하신가요? Core Web Vitals를 망치는 JavaScript 기반 해결책입니다.

Next.js는 페이지별로 선택할 수 있게 해줍니다: 정적 생성, 서버 사이드 렌더링, 또는 ISR을 사용한 하이브리드. 각 라우트에 적합한 도구를 선택합니다.

Next.js로 얻을 수 있는 것

유연한 렌더링 전략

Next.js의 모든 페이지는 다른 렌더링 전략을 사용할 수 있습니다. 마케팅 페이지는 getStaticProps를 사용해 정적 생성을 합니다. 대시보드는 서버 사이드 렌더링을 사용합니다. 블로그는 ISR을 사용해 리빌드 없이 신선함을 유지합니다. 한 프레임워크, 모든 패턴입니다.

GraphQL 없는 데이터 페칭

모든 GraphQL 쿼리를 표준 fetch(), SWR, 또는 선호하는 데이터 라이브러리로 교체합니다. getStaticProps는 페이지 쿼리를 대체합니다. getStaticPaths는 gatsby-node.js의 createPages를 대체합니다. 정신 모델이 더 간단하고 코드가 더 이식 가능합니다.

// Before: gatsby-node.js
exports.createPages = async ({ graphql, actions }) => {
  const result = await graphql(`
    query { allMarkdownRemark { edges { node { frontmatter { slug } } } } }
  `);
  result.data.allMarkdownRemark.edges.forEach(({ node }) => {
    actions.createPage({
      path: node.frontmatter.slug,
      component: path.resolve('./src/templates/post.js'),
    });
  });
};

// After: pages/posts/[slug].tsx
export const getStaticPaths: GetStaticPaths = async () => {
  const posts = await getAllPosts();
  return {
    paths: posts.map((post) => ({ params: { slug: post.slug } })),
    fallback: 'blocking',
  };
};

export const getStaticProps: GetStaticProps = async ({ params }) => {
  const post = await getPostBySlug(params.slug);
  return { props: { post }, revalidate: 60 };
};

Next.js 버전은 더 명확하고, 디버깅하기 쉬우며, 단 하나의 revalidate 속성으로 ISR을 추가합니다.

내장된 이미지 최적화

Next.js <Image> 컴포넌트는 플러그인 없이 지연 로딩, 반응형 크기 조정, 포맷 변환(WebP/AVIF)을 처리합니다. 더 이상 gatsby-plugin-image와 gatsby-transformer-sharp 구성과 씨름할 필요가 없습니다.

API 라우트와 미들웨어

연락 양식 엔드포인트가 필요하신가요? 웹훅 핸들러? 인증 로직? Next.js API 라우트는 동일한 코드베이스에 있습니다. 미들웨어는 리다이렉트, A/B 테스트, 지리적 위치를 엣지에서 처리합니다. Gatsby에는 동등한 것이 없습니다.

당사의 마이그레이션 프로세스

1단계: 감시 및 아키텍처 (1주일)

우리는 모든 Gatsby 페이지, 플러그인, GraphQL 쿼리, 동적 라우트를 집계합니다. 각각은 해당 Next.js와 매핑됩니다. 우리는 대체가 필요한 플러그인을 식별하고 SEO 보존을 위해 현재 URL 구조를 문서화합니다.

2단계: 프로젝트 스캐폴딩 (1-2주일)

우리는 TypeScript로 Next.js 프로젝트를 초기화하고, 헤드리스 CMS 연결을 구성하고, 스타일링 솔루션 — styled-components, Tailwind, CSS Modules 여부에 관계없이 기존 CSS를 마이그레이션 — 을 설정합니다. 그 다음 컴포넌트 아키텍처를 확립합니다.

두 프레임워크 모두 React를 사용하므로, 기존 컴포넌트는 최소한의 변경으로 전송됩니다. 우리는 import를 업데이트하고, gatsby-link를 next/link로 교체하고, gatsby-image를 next/image로 바꾸고, 전역 CSS를 gatsby-browser.js에서 _app.tsx로 이동합니다.

3단계: 데이터 페칭 마이그레이션 (2-3주일)

이것이 핵심 작업입니다. 모든 GraphQL 쿼리는 getStaticProps 또는 getServerSideProps 내부의 직접 API 호출 또는 CMS SDK 메서드가 됩니다. gatsby-node.js의 모든 createPages 호출은 getStaticPaths 함수가 됩니다. 우리는 gatsby-plugin-react-helmet을 Next.js의 기본 <Head> 컴포넌트 또는 App Router 메타데이터 API로 교체합니다.

4단계: 동적 기능 (3-4주일)

Next.js가 앞서는 지점입니다. 우리는 CMS 업데이트가 몇 초 내에 나타나도록 콘텐츠 페이지에 ISR을 추가합니다. 우리는 양식과 통합을 위한 API 라우트를 구현합니다. 우리는 리다이렉트, 인증, 또는 개인화를 위한 미들웨어를 추가합니다 — Gatsby에서는 불가능했거나 매우 어려웠던 기능입니다.

5단계: 테스트 및 시작 (4-5주일)

모든 디바이스에서 전체 회귀 테스트. 모든 템플릿에서 Lighthouse 감시. 현재 사이트에 대한 시각적 차이 테스트. 우리는 모든 URL이 올바르게 해결되는지, 모든 리다이렉트가 작동하는지, 모든 메타 태그가 보존되는지 확인합니다.

SEO 보존 전략

프레임워크 마이그레이션은 부주의하면 SEO 위험입니다. 우리는 그 위험을 제거합니다.

• URL 패리티: 모든 기존 URL은 새 사이트와 1:1로 매핑됩니다. 요청하지 않는 한 구조 변경이 없습니다.
• 301 리다이렉트: 우리는 URL 변경에 대해 next.config.js에서 Next.js 리다이렉트를 구성하며, 완전한 리다이렉트 맵이 있습니다.
• 메타 태그 감시: 우리는 제목 태그, 메타 설명, Open Graph 태그, 정규 URL이 Next.js <Head> 컴포넌트를 사용해 올바르게 전송되는지 확인합니다.
• 구조화된 데이터: Gatsby 사이트의 JSON-LD 마크업은 새 템플릿으로 이식됩니다.
• Sitemap 및 robots.txt: next-sitemap 또는 사용자 정의 API 라우트를 통해 자동으로 생성됩니다.
• 성능 향상: 더 빠른 TTFB와 더 나은 Core Web Vitals 점수는 일반적으로 마이그레이션 후 순위를 해치지 않고 개선합니다.

배포 및 호스팅

우리는 Vercel에서 Next.js의 최고 경험을 위해 배포합니다 — 자동 미리보기 배포, 엣지 함수, 내장 분석, zero-config ISR. 또는 Cloudflare Pages, AWS Amplify, 또는 인프라에 맞는 모든 Node.js 호스팅 환경에 배포할 수 있습니다.

타임라인 및 가격

일반적인 Gatsby에서 Next.js로의 마이그레이션은 사이트 복잡성에 따라 3-5주가 걸립니다:

• 소규모 사이트 (50페이지 미만, 블로그 또는 마케팅 사이트): 2-3주, $6,000부터
• 중규모 사이트 (50-500페이지, CMS 기반, 다중 템플릿): 3-5주, $12,000부터
• 대규모 사이트 (500+ 페이지, 복잡한 데이터 소스, 전자상거래): 5-8주, $20,000부터

모든 마이그레이션에는 엣지 케이스를 파악하고 성능을 미세 조정하기 위한 무료 출시 후 지원 기간이 포함됩니다.

React 장점

이것은 재작성이 아니라 업그레이드입니다. 당신의 팀은 이미 React를 알고 있습니다. 당신의 컴포넌트는 이미 작동합니다. 우리는 중요한 것을 유지하면서 아래의 프레임워크 레이어를 바꾸고 있습니다: 당신의 디자인, 당신의 콘텐츠, 당신의 URL, 당신의 검색 순위.

결과는 더 빠르고, 더 유연하며, Gatsby가 단순히 제공할 수 없는 기능이 가능한 사이트입니다.