TIL: Zustand persist 미들웨어 사용 시 hydration 이슈

문제 상황

Zustand의 persist 미들웨어를 사용해서 로컬 스토리지에 상태를 저장하고 있었는데 Next.js에서 페이지 로드 시 hydration mismatch 경고가 발생했습니다.

서버에서는 초기값으로 렌더링하고 클라이언트에서는 로컬 스토리지의 값으로 렌더링했습니다. 그래서 HTML이 달라지는 거였습니다.

해결 방법

Zustand에서 제공하는 onRehydrateStorage 콜백과 커스텀 훅을 조합해서 해결했습니다. 핵심은 클라이언트에서 hydration이 완료되고 나서야 persist된 값을 사용하는 것입니다.

배운 점

SSR 환경에서 클라이언트 전용 스토리지를 사용할 때는 hydration 타이밍을 고려해야 합니다. "서버에서 이 값에 접근할 수 있는가?"를 먼저 생각하는 습관이 중요하다는 걸 다시 느꼈습니다.