Next.js에서 useLocalStorag 사용 시 에러가 발생하는 문제

[suhyeoonn]

Next.js에서는 서버 사이드 렌더링(SSR)과 클라이언트 렌더링을 모두 수행하는데, createLocalStorageManager 함수에서 LocalStorage 인스턴스를 생성할 때 클라이언트 환경이 아니면 에러를 반환하도록 되어 있어, SSR 시 500 에러가 발생합니다. 서버 사이드 렌더링 시에는 브라우저 API인 localStorage를 사용할 수 없으므로, 서버 사이드에서 LocalStorage 인스턴스가 생성되지 않도록 예외 처리가 필요합니다.

에러 내용

 ⨯ src/lib/hooks/useLocalStorage.ts (102:13) @ new LocalStorage
 ⨯ Error: localStorage is not available in this environment. Please ensure you are running this code in a browser.
    at new LocalStorage (./src/lib/hooks/useLocalStorage.ts:89:19)
    at createLocalStorageManager (./src/lib/hooks/useLocalStorage.ts:58:21)
    at useLocalStorage (./src/lib/hooks/useLocalStorage.ts:21:74)
    at Home (./src/app/page.tsx:32:90)
digest: "4014735887"
  100 |     if (!validators.isClient()) {
  101 |       console.log("server call");
> 102 |       throw new Error(
      |             ^
  103 |         "localStorage is not available in this environment. Please ensure you are running this code in a browser."
  104 |       );
  105 |     }
 GET / 500 in 241ms

훅 사용 코드

"use client";

export default function Home() {
  const [user] = useLocalStorage<IUser | null>("user", null);
  const [token] = useLocalStorage("token", "");
  console.log(token);
  // ...

문제되는 부분

const useLocalStorage = <T>(key: string, initialValue: T) => {
  const storageManager = useRef(createLocalStorageManager<T>(key));
 // ...
}

const createLocalStorageManager = <T>(key: string) => {
  const storage = new LocalStorage(); //<- 서버 사이드 렌더링 시 에러 발생
  // ...
}

해결 방안

const createLocalStorageManager = <T>(key: string) => {
  const storage = validators.isClient() ? new LocalStorage() : null; // <- 클라이언트 환경이 아닐 경우 null 반환
}

개인 프로젝트에서 문제 해결했던 코드 공유드립니다! https://github.com/suhyeoonn/book-rating-frontend/commit/faf68efb4782fa0bb4779de2b32a29c63fa54e98