[Next.js] sessionStorage is not defined 오류

ReferenceError: sessionStorage is not defined

Next.js에서 sessionStorage.getItem("myKey")를 사용하면, 값은 정상적으로 가져와지지만 위와 같은 오류가 발생할 수 있습니다. 이게 왜 그런 걸까요?

이유는 간단합니다. Next.js는 서버에서도 실행되지만 sessionStorage는 브라우저에서만 동작하는 API이기 때문입니다.
그렇다면 이 문제를 어떻게 해결할 수 있을까요? 함께 알아보겠습니다.

■ sessionStorage

sessionStorage는 브라우저(Web API)에서 제공하는 기능입니다.
즉, HTML을 띄우는 브라우저에서만 사용할 수 있고, 서버에서는 사용할 수 없는 객체입니다.

const value = sessionStorage.getItem("myKey"); // ✅ 브라우저에서는 정상 동작
console.log(value);

이 코드는 일반적인 React 환경에서는 문제없이 실행됩니다.(관련해서 같이 읽으면 좋은 글)
하지만 Next.js에서는 서버에서 먼저 실행되기 때문에, sessionStorage를 만나면 오류가 발생할 수 있어요.

■ 오류가 발생하는 이유

Next.js는 SSR(Server-Side Rendering) 을 기본적으로 수행합니다.
즉, 페이지가 먼저 서버(Node.js 환경)에서 실행된 후, 그 결과를 브라우저로 전달하는 방식이에요.

그런데 sessionStorage는 브라우저 환경에서만 존재하기 때문에, 서버에서 실행될 때는 사용할 수 없습니다.
그렇다 보니 Next.js가 서버에서 코드를 실행하다가 sessionStorage를 만나면 "이거 서버에는 없는데?" 하면서 오류를 발생시키는 것이죠.

즉, 서버에서는 브라우저 API가 없기 때문에 sessionStorage를 직접 사용하면 안 됩니다.

■ 해결 방법

이 문제를 해결하려면 useEffect를 사용하면 됩니다.
useEffect는 컴포넌트가 마운트된 후(즉, 브라우저에서 실행된 후)에 동작하기 때문에 sessionStorage를 안전하게 사용할 수 있어요.

import { useEffect, useState } from "react";

const MyComponent = () => {
  const [value, setValue] = useState<string | null>(null);

  useEffect(() => {
    if (typeof window !== "undefined") { // ✅ 서버에서 실행되지 않도록 방지
      const storedValue = sessionStorage.getItem("myKey");
      setValue(storedValue);
    }
  }, []);

  return <div>Session Value: {value}</div>;
};

export default MyComponent;

■ 결론

1. Next.js는 기본적으로 SSR(Server-Side Rendering) 을 수행하기 때문에, 서버에서도 코드가 실행됩니다.
2. sessionStorage는 브라우저에서만 사용할 수 있는 API라서, 서버에서 실행되면 오류가 발생할 수 있습니다.
3. useEffect를 사용하면 브라우저에서만 실행되므로, sessionStorage를 안전하게 사용할 수 있어요.

즉, Next.js에서 sessionStorage를 사용하려면 반드시 useEffect 안에서 실행해야 오류 없이 사용할 수 있습니다!