Zustand persist

처음에는 전역 상태는 페이지를 이동하거나 새로고침하면 초기화되는 것이 당연하다고 생각했다.

그런데 실제 서비스를 만들다 보면 새로고침 후에도 유지되어야 하는 UI 상태가 꽤 많다.

예를 들어 상품 목록 페이지에서 사용자가 이런 필터를 설정했다고 하자.

카테고리: 노트북
정렬: 낮은 가격순
가격 범위: 50만원 ~ 150만원
재고 있는 상품만 보기

사용자가 상세 페이지에 들어갔다가 다시 목록으로 돌아왔을 때,
필터가 전부 초기화되면 사용성이 좋지 않다.

이런 상태는 서버 인증 정보처럼 민감한 값은 아니지만,
사용자 경험을 위해 브라우저에 유지해둘 만한 값이다.

이때 Zustand의 persist를 사용할 수 있다.

persist는 store 상태를 localStorage나 sessionStorage에 저장하고,
페이지를 다시 열었을 때 저장된 값을 복원해주는 middleware다.

왜 user 정보는 안되는가

persist 예시에서 종종 user를 localStorage에 저장하는 코드를 볼 수 있다.

이건 위험하다.

localStorage는 JavaScript로 접근 가능하기 때문에 XSS에 취약하다.

또 브라우저 저장소는 사용자가 직접 수정할 수도 있다.

그래서 인증 정보나 사용자 권한 판단에 필요한 값은 persist에 저장하지 않는 편이 좋다.

반면 상품 필터 상태는 다르다.

저장되어도 보안 문제가 거의 없음
사용자가 직접 수정해도 치명적이지 않음
새로고침 후 유지되면 UX가 좋아짐
서버 권한 판단과 무관함

그래서 persist의 실무 예시로는 user보다 filter, theme, sidebar, draft 같은 UI 상태가 훨씬 적합하다.

기본 코드

상품 목록 필터 store를 만든다.

import { create } from 'zustand';
import { persist } from 'zustand/middleware';

type Sort = 'latest' | 'price_asc' | 'price_desc';

type ProductFilterState = {
  category: string | null;
  sort: Sort;
  minPrice: number | null;
  maxPrice: number | null;
  inStockOnly: boolean;
  hasHydrated: boolean;

  setCategory: (category: string | null) => void;
  setSort: (sort: Sort) => void;
  setPriceRange: (minPrice: number | null, maxPrice: number | null) => void;
  setInStockOnly: (value: boolean) => void;
  resetFilter: () => void;
  setHasHydrated: (value: boolean) => void;
};

const initialFilter = {
  category: null,
  sort: 'latest' as Sort,
  minPrice: null,
  maxPrice: null,
  inStockOnly: false,
};

export const useProductFilterStore = create<ProductFilterState>()(
  persist(
    (set) => ({
      ...initialFilter,
      hasHydrated: false,

      setCategory: (category) => set({ category }),
      setSort: (sort) => set({ sort }),
      setPriceRange: (minPrice, maxPrice) =>
        set({ minPrice, maxPrice }),
      setInStockOnly: (value) => set({ inStockOnly: value }),

      resetFilter: () => set(initialFilter),

      setHasHydrated: (value) => set({ hasHydrated: value }),
    }),
    {
      name: 'product-filter-storage',

      partialize: (state) => ({
        category: state.category,
        sort: state.sort,
        minPrice: state.minPrice,
        maxPrice: state.maxPrice,
        inStockOnly: state.inStockOnly,
      }),

      onRehydrateStorage: () => (state) => {
        state?.setHasHydrated(true);
      },
    }
  )
);

여기서 중요한 포인트는 두 가지다.

1. partialize로 저장할 값 제한

partialize: (state) => ({
  category: state.category,
  sort: state.sort,
  minPrice: state.minPrice,
  maxPrice: state.maxPrice,
  inStockOnly: state.inStockOnly,
}),

persist는 기본적으로 store 상태를 저장한다.

하지만 실무에서는 모든 상태를 저장하면 안 된다.

예를 들어 hasHydrated 같은 값은 저장할 필요가 없다.

함수도 저장 대상이 아니다.

그래서 실제로 브라우저 저장소에 남겨야 하는 값만 partialize로 제한하는 게 좋다.

이렇게 하지 않으면 시간이 지나면서 localStorage에 불필요한 상태가 쌓이고,
store 구조가 바뀌었을 때 오래된 데이터 때문에 버그가 생길 수 있다.

2. hasHydrated로 복원 완료 여부 관리

hasHydrated: false,

onRehydrateStorage: () => (state) => {
  state?.setHasHydrated(true);
},

Next.js SSR 환경에서는 서버가 localStorage를 알 수 없다.

그래서 서버 렌더링 시점에는 항상 초기 필터 상태다.

서버 렌더링: sort = latest
클라이언트 복원 후: sort = price_asc

이때 UI가 바로 필터 상태를 기준으로 렌더링되면 서버와 클라이언트의 화면이 달라질 수 있다.

그래서 복원이 끝나기 전에는 필터 UI를 확정하지 않는다

동작 흐름

1. 사용자가 필터 변경
2. Zustand store 상태 변경
3. persist가 localStorage에 저장
4. 페이지 새로고침
5. store는 초기값으로 시작
6. localStorage 값으로 rehydrate
7. hasHydrated = true
8. 복원된 필터 기준으로 UI 렌더링

SSR 환경에서 발생할 수 있는 문제

예를 들어 서버는 기본 필터로 HTML을 만든다.

sort = latest

그런데 사용자의 localStorage에는 이전 선택값이 남아 있다.

sort = price_asc

그러면 클라이언트에서 복원 후 화면이 바뀐다.

서버 HTML: 최신순 선택
클라이언트 복원 후: 낮은 가격순 선택

이 차이가 hydration mismatch나 UI 깜빡임으로 이어질 수 있다.

그래서 persist 상태를 기준으로 UI가 크게 달라지는 경우에는 hasHydrated 체크가 필요하다.

API 요청과 연결할 때 주의할 점

필터 상태는 보통 상품 목록 API 요청과 연결된다.

const { category, sort, inStockOnly } = useProductFilterStore();

useEffect(() => {
  fetchProducts({
    category,
    sort,
    inStockOnly,
  });
}, [category, sort, inStockOnly]);

이때 hasHydrated를 고려하지 않으면 문제가 생긴다.

초기값으로 API 요청
→ localStorage 복원
→ 복원된 값으로 API 재요청

즉 불필요한 요청이 두 번 발생한다.

그래서 복원 이후에만 요청하는 편이 좋다.

const hasHydrated = useProductFilterStore((state) => state.hasHydrated);

useEffect(() => {
  if (!hasHydrated) return;

  fetchProducts({
    category,
    sort,
    inStockOnly,
  });
}, [hasHydrated, category, sort, inStockOnly]);

이게 꽤 중요하다.

persist 문제는 단순히 화면 mismatch만이 아니라,
불필요한 API 요청까지 만들 수 있다.

Query String과 Persist

상품 필터처럼 URL과 연결되는 상태라면 고민이 하나 더 생긴다.

필터 상태를 localStorage에 둘 것인가?
URL query string에 둘 것인가?

예를 들어

/products?category=laptop&sort=price_asc

URL에 필터를 넣으면 장점이 있다.

공유 가능
뒤로가기/앞으로가기 자연스러움
SEO에 유리할 수 있음
서버에서도 query를 알 수 있음

반면 localStorage는

사용자 개인 설정 유지에 좋음
URL이 지저분해지지 않음
임시 UI 상태 저장에 적합함

그래서 이렇게 생각한다.

검색 결과에 영향을 주는 핵심 필터
→ URL query string

개인화된 UI 보조 상태
→ Zustand persist

예를 들어

category, keyword, sort
→ URL

viewMode, recentFilter, inStockOnly 기본값
→ persist

이렇게 책임을 나누면 구조가 훨씬 안정적이다.

persist에 적합한 예시

persist는 이런 상태에 적합하다.

다크모드
상품 목록 viewMode(grid/list)
최근 본 상품 ID 목록
임시 작성 중인 글
사이드바 접힘 여부
사용자가 마지막으로 선택한 정렬 옵션

반대로 이런 상태는 조심해야 한다.

로그인 토큰
권한 정보
결제 정보
민감한 사용자 정보
서버 검증이 필요한 데이터

핵심 기준은 이거다.

localStorage 값이 조작되어도 서비스의 보안이나 데이터 정합성이 깨지지 않는가?

깨지지 않는다면 persist 후보가 될 수 있다.

Persist, Rehydrate