[Next.js] 'sessionStorage is not defined' 문제

Next.js는 SSR(Sever Side Rendering) 을 지원하는 React 프레임워크이다. SSR(Sever Side Rendering)은 클라이언트(브라우저) 대신 서버에서 초기 HTML을 생성하고 렌더링하는 방식이다.

💥 위 접근 방식은 여러 가지 이점을 제공하지만 window, document, sessionStorage와 같은 브라우저 전역 객체를 직접 사용할 수 없다!

왜 직접 사용할 수 없을까?

Next.js의 SSR은 React 컴포넌트를 브라우저가 아니라 Node.js 환경에서 먼저 렌더링하는 방식이다. 초기 HTML을 서버에서 미리 만들어 클라이언트에 보내주는 구조인데, 이 때 Node.js는 브라우저가 아니기 때문에 브라우저 전역 객체인 window, document, sessionStorage 와 같은 브라우저 전용 API가 존재하지 않는 것이다.

따라서 서버 사이드 렌더링(SSR) 또는 정적 사이트 생성(SSG) 과정에서 이러한 객체에 접근하려고 하면 *참조 오류(ReferenceError: sessionStorage is not defined)가 발생하는 것이다. 그래서 페이지가 cilent에 로드될때까지 sessionStorage에 접근 불가능하다.

✅ SSR 환경에서 브라우저 API를 안전하게 다루는 방법

1. 조건문 window 존재 여부 확인

typeof window !== "undefined"를 사용하여 window 객체가 존재하는지 확인한다. 이 조건문은 서버에서는 false가 되어 해당 코드 블록을 건너뛰게 하고, 클라이언트에서는 true가 되어 코드를 실행한다.

if (typeof window !== "undefined") {
  // 클라이언트 사이드에서만 실행될 코드
  sessionStorage.getItem('key');
}

2. useEffect로 클라이언트에서만 실행

React의 useEffect 훅은 컴포넌트가 렌더링된 후 클라이언트 사이드에서만 코드를 실행할 수 있기 때문에 useEffect 내부에서 브라우저 전역 객체를 안전하게 사용할 수 있는 것이다.

import { useEffect, useState } from 'react';

export default function ExampleComponent() {
const [token, setToken] = useState(null);

useEffect(() => {
  const storedToken = sessionStorage.getItem("accessToken");
  setToken(storedToken);
}, []);

return <div>Token: {token}</div>;
}