프로젝트 개요

• 문제: React Native와 웹뷰를 결합한 초기 아키텍처의 높은 관리 비용과, 검색 엔진 크롤링이 불가능하여 SEO라는 핵심 비즈니스 목표를 달성할 수 없는 문제.
• 해결: 주요 SSR 프레임워크(Gatsby, Remix, Next.js)의 기술적 트레이드오프를 비교 분석하여 Next.js를 최종 선정. 마이그레이션을 주도하며 Hydration 오류 등 핵심 기술 문제를 해결하고 단일 코드베이스 아키텍처를 구축.
• 성과: 코드베이스 통합으로 운영 비용 절감. Lighthouse SEO 점수 100점 달성 및 FCP 1.7초로 75% 개선 등 정량적 성과를 통해 비즈니스의 신규 트래픽 확보 전략에 기여. RSC 경계 문제를 해결하며 서버-클라이언트 시스템 설계 원칙 정립.

문제 정의

초기 기획은 React Native와 웹뷰를 결합한 하이브리드 앱이었습니다. 그러나 개발 과정에서 네이티브와 웹뷰 간 통신 브릿지의 관리 비용이 예상보다 크다는 것을 확인했습니다. 결국 개발 방향을 PWA기반의 웹 아키텍처로 전환하게 되었습니다. 따라서 검색 엔진에 친화적인 독립 웹사이트를 구축하고, 초기 렌더링 시 콘텐츠를 모두 보여주는 서버 사이드 렌더링의 도입은 선택이 아닌 필수였습니다.

기술 스택 선정: 왜 Next.js였는가?

React 기반의 주요 SSR 프레임워크인 Gatsby, Remix, Next.js를 두고 최종 검토했습니다. SSR은 필수였지만, 모든 페이지에 동일한 전략을 적용하는 건 기술 부채로 가는 지름길이었습니다.

Gatsby의 빌드-타임 데이터 소싱은 실시간 데이터가 핵심인 우리 서비스와 맞지 않았습니다. Remix의 loader 모델은 아키텍처의 일관성은 높지만, 단순 콘텐츠 페이지까지 서버 로직을 강제하는 오버엔지니어링이라고 판단했습니다.

결국 Next.js를 선택했습니다. 이 프레임워크만이 SEO가 필수적인 페이지엔 SSR을, 후속 상호작용엔 CSR을, 그리고 미래의 이벤트 페이지엔 SSG를 하나의 프로젝트 안에서 모두 구현할 수 있게 해주었습니다.

Vercel을 통한 원클릭 배포와 인프라적 편의성, 그리고 시장 점유율 1위가 보장하는 생태계는 기술 외적인 측면에서도 Next.js를 선택할 수밖에 없게 만들었습니다.

핵심 문제 해결: Hydration Mismatch와 RSC 경계

마이그레이션 과정에서 가장 빈번하게 마주한 문제는 Hydration 오류였습니다.

특히 서버컴포넌트 코드에서 window나 localstorage 접근을 직접적으로 하지 않았음에도 알 수 없는 Hydration에러가 계속 발생했습니다. 결국 FSD 디렉토리의 배럴 index 파일에서 클라이언트 코드가 서버코드와 같이 export되는 문제임을 알았습니다.

이는 단순히 서버와 클라이언트의 렌더링 결과물이 다르다는 표면적인 현상이 아니라, React Server Components(RSC) 아키텍처의 동작 방식을 이해해야만 해결할 수 있는 문제였습니다.

• Hydration과 RSC에 대해서

use client