Next.js SSR 환경에서 'window is not defined' 오류 해결과 Isomorphic 코드 작성법

Next.js SSR 환경에서 'window is not defined' 오류 해결과 Isomorphic 코드 작성법

핵심 기술

본 콘텐츠는 Next.js와 같은 서버 사이드 렌더링(SSR) 프레임워크 사용 시 발생하는 ReferenceError: window is not defined 오류의 원인을 설명하고, 브라우저와 서버 환경의 차이를 극복하기 위한 Isomorphic 코드 작성 방식을 제시합니다.

기술적 세부사항

• SSR의 기본 이해: SSR은 서버에서 React 컴포넌트를 실행하여 완성된 HTML을 생성하고 브라우저에 전달하여 초기 로딩 속도 및 SEO에 유리합니다.
• 오류 발생 원인: SSR은 Node.js 기반 서버 환경에서 실행되며, 이 환경에는 window, document와 같은 브라우저 전용 객체가 존재하지 않기 때문에 발생합니다.
  • 예시: const name = new URL(location.href).searchParams.get('name'); (SSR 환경에서 location is not defined 에러 발생)
• Hydration과 Hydration Mismatch: SSR로 전달된 HTML에 클라이언트 측 JavaScript 로직과 상태를 연결하는 과정을 Hydration이라고 합니다. 서버와 클라이언트의 데이터 또는 렌더링 결과가 일치하지 않으면 Warning: Text content did not match (Hydration Mismatch) 경고가 발생합니다.
• SSR 실행 흐름:
  1. 서버에서 React 컴포넌트 실행 -> HTML 문자열 생성.
  2. 필요한 초기 상태(props)를 JSON으로 직렬화하여 <script id="__NEXT_DATA__">에 포함.
  3. 브라우저가 HTML 렌더링 후, 직렬화된 데이터로 ReactDOM.hydrate() 실행.
  4. 클라이언트가 동일한 구조의 가상 DOM 생성 및 상호작용 가능한 React 앱으로 전환.
• Isomorphic 코드: 서버와 클라이언트 양쪽 환경 모두에서 동일하게 실행될 수 있는 코드를 작성하여 SSR 관련 오류를 방지하고 일관된 렌더링을 보장합니다.
  • getServerSideProps 예시: 서버에서 new Date()를 사용하여 serverTime을 생성하고 props로 전달하여 클라이언트와 UI 일치성을 보장합니다.
  • 오류 발생 예시: 클라이언트에서만 new Date()를 사용하여 now 값을 생성하면 서버와 클라이언트의 렌더링 결과가 달라져 Hydration mismatch 발생 가능성이 있습니다.

개발 임팩트

• SSR 환경에서 흔히 발생하는 브라우저 환경 의존성 오류를 효과적으로 예방할 수 있습니다.
• 서버와 클라이언트 간의 렌더링 일관성을 유지하여 사용자 경험을 개선하고 디버깅 시간을 단축합니다.
• SSR의 장점(빠른 초기 로딩, SEO)을 극대화하면서 안정적인 애플리케이션을 구축할 수 있습니다.

커뮤니티 반응

(본문 내용에 커뮤니티 반응에 대한 직접적인 언급은 없습니다.)