Next.js 15에서 발생한 Hydration 오류와 해결 과정

Next.js 15로 업데이트한 뒤, 예상치 못한 Hydration 오류가 발생했다. typeof window !== 'undefined' 같은 조건문을 사용하는 코드에서 특히 문제가 심했다. SSR과 CSR에서 HTML이 다르게 렌더링되면서 React가 이를 감지하고 경고를 띄웠다. 해결하기 위해 여러 가지 시도를 해봤지만, 결국 Next.js 14와 React 18.2.0으로 다운그레이드하는 것이 가장 안정적인 방법이었다.

Hydration 오류의 주요 원인

1. typeof window !== 'undefined'** 사용**: Next.js 15에서는 SSR과 CSR에서 typeof window 조건문이 불일치를 일으킬 가능성이 높아졌다.
2. 스타일 동적 변경: GSAP, Swiper 같은 라이브러리들이 CSR 단계에서 스타일을 변경하면서 SSR에서 미리 렌더링된 HTML과 차이가 발생했다.
3. 라이브러리 호환성 문제: Next.js 15에서 일부 라이브러리(예: Swiper, GSAP, Framer Motion 등)가 SSR과 CSR에서 다르게 동작하면서 예상치 못한 문제가 발생했다.

해결 방법: Next.js 14 및 React 18.2.0으로 다운그레이드

Next.js 15에서 발생한 여러 문제를 해결하기 위해 결국 Next.js 14 및 React 18.2.0으로 다운그레이드했다. 최신 기능을 유지하면서도 Hydration 오류를 방지할 수 있는 가장 현실적인 선택이었다.

안정적인 버전 조합

"dependencies": {
    "framer-motion": "^11.0.0",
    "gsap": "^3.12.5",
    "imagesloaded": "^5.0.0",
    "next": "^14.2.0",
    "react": "^18.2.0",
    "react-dom": "^18.2.0",
    "react-parallax-tilt": "^1.7.272",
    "swiper": "^11.0.5"
}

다운그레이드 명령어

npm install next@14.2.0 react@18.2.0 react-dom@18.2.0 \
    framer-motion@11.0.0 gsap@3.12.5 imagesloaded@5.0.0 \
    react-parallax-tilt@1.7.272 swiper@11.0.5

기존 빌드 및 의존성 정리 후 재설치

rm -rf .next node_modules package-lock.json yarn.lock
npm install

정상적으로 적용되었는지 확인

npm list next react react-dom framer-motion swiper gsap imagesloaded react-parallax-tilt

예상되는 결과

next@14.2.0
react@18.2.0
react-dom@18.2.0
framer-motion@11.0.0
gsap@3.12.5
swiper@11.0.5
react-parallax-tilt@1.7.272
imagesloaded@5.0.0

다운그레이드 후 얻은 점

1. Hydration 오류 해결: typeof window !== 'undefined'를 사용할 때 발생하는 SSR/CSR 불일치 문제 해결.
2. Next.js 14와 React 18.2.0의 안정적인 호환성 유지.
3. GSAP 및 Swiper 등의 애니메이션 라이브러리 충돌 방지.
4. Next.js 15에서 발생한 스타일 변경 문제 해결.

결국 Next.js 14 + React 18.2.0 + 최신 Swiper & Framer Motion 조합이 가장 안정적인 개발 환경을 제공했다. 당분간은 이 조합을 유지하면서 추후 Next.js 15가 안정화되면 다시 업그레이드를 고려해볼 예정이다.

회고 

이번 경험을 통해, 프로젝트를 시작할 때 라이브러리의 버전과 호환성을 미리 충분히 검토하는 것이 중요하다는 걸 깨달았다. 버전 충돌이나 예상치 못한 오류를 피하려면, 단순히 최신 버전을 사용하는 것이 아니라 해당 프로젝트에 가장 적합한 환경을 구축해야 한다는 점을 기억해야겠다.