Next.js + Zustand: Hydration 문제 해결하기

이번에 새 프로젝트를 시작하면서 SEO를 어느정도 고려해야했기 때문에 next.js를 도입하게 되었습니다. 클라이언트 상태 관리는 직관적인 Zustand를 활용했고 API 통신은 익숙한 axios를 이용해서 호출했습니다.

개발을 진행하면서 서버와 클라이언트 컴포넌트 간의 상태 불일치로 인한 헤더 깜빡임 이슈를 겪게 되었고 이를 해결 해나간 과정을 정리해보려고 합니다!

1. 새로고침 시 헤더가 깜빡 거리는 현상 발생

처음 문제를 인식한건 로그인 상태에서 새로고침 했을 때 였습니다.
로그인 상태임에도 불구하고,

• 헤더가 잠깐 비로그인 상태로 깜빡임
• 다시 로그인 상태로 전환되는 현상이 발생했습니다.

브라우저 새로고침 시에 항상 발생하는 문제였고, CSR 환경에서는 문제가 없던 문제였기 때문에 SSR 동작 과정에서의 상태 처리 문제라고 생각하게 되었습니다.

2. Next.js의 렌더링 방식과 Hydration

💡 Next.js는 곧 SSR이 아니다.

많은 사람들이 착각하는 부분인데, Next.js ≠ SSR입니다.
Next.js는 CSR, SSR, SSG를 자유롭게 혼합할 수 있는 하이브리드 프레임워크입니다.

Next.js App Router의 컴포넌트 구분

app/디렉토리를 기준으로 컴포넌트는 아래처럼 나뉩니다.

• 서버 컴포넌트 (기본): 서버에서 HTML을 렌더링하고 클라이언트에는 JS가 전송되지 않음
• 클라이언트 컴포넌트 ("use client" 필요): 상태관리, 이벤트 핸들링 등 클라이언트 환경에서만 동작

Hydration 과정에서 상태 불일치 문제

이런 구조로 인해 서버와 클라이언트에서의 상태가 일치하지 않으면 Hydration시 깜빡임 또는 UI 불일치가 발생할 수 있습니다.

3. 문제 해결 시도

3-1) 첫 번째 시도: 클라이언트에서 세션을 재 동기화

처음에는 클라이언트에서 Zustand 상태를 동기화하는 sessionHydration 컴포넌트를 만들었습니다.

"use client"

import { useEffect } from "react"
import { useUserStore } from "@/store/user"
import { getSession } from "@/lib/auth"

export function SessionHydration() {
  const setUser = useUserStore((state) => state.setUser);

  useEffect(() => {
    getSession().then((session) => {
      if (session) {
      	setUser(session.user);
      }
    });
  }, []);

  return null;
}

Header 컴포넌트는 이 상태를 바라보고 렌더링 하도록 처리해보았지만,

• 페이지가 처음 서버에서 렌더링 될 때는 상태를 알지 못함
• 클라이언트에서 Zustand가 업데이트가 되기 전 까지는 비로그인 상태로 보이는 깜빡임이 여전히 발생했습니다.

3-2) 두 번째 시도: 서버 컴포넌트에서 세션 상태 가져오기

서버에서 세션 상태를 먼저 가져오고 그 결과를 Header에 props로 넘기면 어떨까 생각해서 시도해보았습니다.

// layout.tsx
import { fetchSession } from "@/lib/auth"

export default async function Layout({ children }: PropsWithChildren) {
  const session = await fetchSession();

  return (
    <>
      <Header session={session} />
      {children}
    </>
  );
}

이렇게 하면 SSR 단계에서 로그인 상태를 미리 알고 있기 때문에 상태 불일치에 따른 깜빡임이 더이상 일어나지 않았습니다. 👏🏻

그렇지만....

4. 실서버에 배포 후, 예상치 못한 문제 발생

실제로 서버에 배포 후 사내에서 테스트 해보니 로그인 호출은 정상적으로 동작했는데, 로그인 상태로 전환되지 않는 문제가 발생했습니다.

근본 원인 분석: Next.js 서버에서의 API 호출 위험성

왜 그런지 원인을 찾는데 헤매던 와중, 백엔드 개발자 동료의 조언이 있었습니다.

Next 서버에서 API를 호출하는 방식이면, 다중 사용자 환경에서 세션이 꼬일 수도 있습니다.
예를 들면, 쇼핑몰에서 내 계정으로 로그인했는데 다른 사람 장바구니가 보이는 문제와 비슷해요.
세션 상태는 항상 클라이언트에서 판단하는 게 안전합니다.

왜 이런 문제가 발생할까?

Next.js 서버에서 API 호출 시 발생할 수 있는 문제들

• 쿠키 전달 문제: Next.js 서버에서 백엔드 API를 호출할 때 브라우저의 쿠키가 제대로 전달되지 않을 수 있음
• 서버 인스턴스 공유: 여러 사용자의 요청이 같은 서버 인스턴스에서 처리되면서 상태가 꼬일 가능성
• 네트워크 지연: 서버-서버 통신에서의 타임아웃이나 지연으로 인한 상태 불일치

다중 사용자 환경에서의 위험성

이런 구조에서는 사용자 A의 세션 정보가 사용자 B에게 잘못 전달될 위험이 있습니다.

layout.tsx에서의 과도한 API 호출 문제

또한, layout.tsx에서 세션 상태를 확인하면 모든 페이지 요청마다 API가 호출되어

• 불필요한 서버 부하 증가
• 응답 지연으로 인한 사용자 경험 저하
• API 호출 실패 시 전체 페이지 렌더링 지연

위와 같은 문제들이 발생할 수 있었습니다.

5. 최종 해결 방법: 쿠키 기반 SSR + 클라이언트 동기화

그래서 다시 구조를 변경해보았습니다.

• layout.tsx에서 Next.js의 cookies()를 사용해 sid 쿠키가 있는지만 확인
• 이 정보로 isLoggedIn props만 Header에 내려줌
• 클라이언트에서 Zustand는 알아서 hydration 되도록 설정

import { cookies } from "next/headers"

export default function Layout({ children }: PropsWithChildren) {
  const hasSid = cookies().has("sid");

  return (
    <>
      <Header isLoggedIn={hasSid} />
      {children}
    </>
  );
}

Zustand 설정

store에서 skipHydration옵션을 설정하거나 서버에서 초기화 되지 않도록 설정해주었습니다.

persist(
  (set) => ({
    user: null,
    setUser: (u) => set({ user: u }),
  }),
  {
    name: "user-store",
    skipHydration: true,
  }
)

마무리

이번 문제 해결을 통해서

• Next.js는 하이브리드 프레임워크입니다. SSR만의 프레임워크가 아니라 CSR/SSR/SSG를 상황에 맞게 조합할 수 있습니다.
• 서버와 클라이언트의 역할을 명확히 분리해야 합니다. 서버에서는 최소한의 정보만 판단하고, 상세한 상태 관리는 클라이언트에서 처리하는 것이 안전합니다.
• 다중 사용자 환경에서의 보안을 항상 고려해야 합니다. 서버에서 사용자별 API를 호출할 때는 세션 꼬임 위험을 인지해야 합니다.

🔗 참고자료

• Zustand - SSR & Hydration 공식 문서
• Next.js App Router Docs
• Next.js 렌더링 동작 원리 with Hydration
• 렌더링 삼형제 CSR, SSR, SSG 이해하기

혹시 더 좋은 해결 방법이나 다른 접근법을 알고 계시다면 언제든지 알려주세요.
잘못된 내용이나 개선할 점이 있다면 언제든 피드백 부탁드립니다. 감사합니다. 🙇🏻‍♀️