zustand

Zustand Quick Reference

Version: 5.x (v5) Doc Source: Official Zustand documentation

🎯 Skill 목적

Zustand v5를 사용한 클라이언트 상태 관리 구현 시 베스트 프랙티스를 적용합니다. store 생성, selector 패턴, shallow 비교를 통한 리렌더 최적화, Slices Pattern으로 대규모 store 분할, TypeScript 타이핑, persist/devtools/immer 미들웨어 활용, Next.js SSR 통합 등 Zustand의 핵심 패턴을 올바르게 구현하도록 안내합니다.

🔑 활성화 조건

활성화 키워드

• "zustand", "Zustand"
• "create store", "createStore"
• "useStore", "useShallow"
• "상태 관리", "state management" (클라이언트 상태)
• "슬라이스 패턴", "slices pattern"
• "persist middleware", "devtools middleware"
• "immer middleware"

필수 조건

• Zustand를 사용하는 프로젝트에서 작업 중일 때
• 클라이언트 상태 관리 로직 구현 시
• store 설계, 미들웨어 설정, 리렌더 최적화가 필요할 때

---

Dependencies

npm install zustand
# Optional
npm install immer                      # immer middleware
npm install @redux-devtools/extension  # devtools middleware
npm install use-sync-external-store    # traditional (equality fn)

---

⚠️ v5 Key Points

항목	설명
create<T>()(...)	TypeScript에서 curried form 필수 (제네릭 추론 한계)
set shallow merge	set은 1단계만 merge, 중첩 객체는 spread 필요
set(state, true)	두 번째 인자 true로 merge 대신 replace
useShallow	selector 반환값의 shallow 비교로 불필요한 리렌더 방지
store.getInitialState()	store 리셋에 활용
RSC 금지	React Server Components에서 store 읽기/쓰기 금지

---

Store Creation Guide

상황	API
React에서 기본 store	create (zustand)
React 외부 (vanilla)	createStore (zustand/vanilla)
커스텀 equality 체크	createWithEqualityFn (zustand/traditional)
타입 자동 추론	combine middleware

---

Hook Selection Guide

상황	훅
create로 만든 store 사용	useSomeStore((s) => s.value)
vanilla store를 React에서 사용	useStore(store, selector)
커스텀 equality 체크	useStoreWithEqualityFn(store, selector, equalityFn)
여러 프로퍼티 선택 (리렌더 최적화)	useShallow((s) => ({ a: s.a, b: s.b }))

---

Middleware Composition

// 권장 순서: devtools를 가장 바깥에
create<Store>()(
  devtools(
    persist(
      immer((set) => ({
        // state & actions
      })),
      { name: 'my-storage' },
    ),
  ),
)

devtools는 가능한 가장 바깥쪽에 위치시킵니다.

---

📚 When to Read Additional Files

Guides

State Updates

Updating state? → references/guides/01-updating-state.md

• flat updates, deeply nested object, Immer 활용

Immutable state and merging? → references/guides/04-immutable-state-and-merging.md

• set shallow merge 동작, nested objects, replace flag

Maps and Sets usage? → references/guides/05-maps-and-sets-usage.md

• Map/Set 업데이트 시 새 인스턴스 생성 필수

How to reset state? → references/guides/16-how-to-reset-state.md

• store.getInitialState(), 다중 store 리셋

Store Patterns

No store actions? → references/guides/02-practice-with-no-store-actions.md

• 모듈 레벨 actions, 코드 스플리팅

Slices pattern? → references/guides/03-slices-pattern.md

• store 분할, 결합, 미들웨어 적용

Flux inspired practice? → references/guides/15-flux-inspired-practice.md

• single store, colocate actions, Redux-like 패턴

Auto generating selectors? → references/guides/11-auto-generating-selectors.md

• createSelectors 유틸리티, .use.property() 패턴

Performance

Prevent rerenders with useShallow? → references/guides/06-prevent-rerenders-with-use-shallow.md

• useShallow로 불필요한 리렌더 방지

TypeScript

Beginner TypeScript? → references/guides/09-beginner-typescript.md

• 기본 타이핑, ExtractState, middlewares, async actions

Advanced TypeScript? → references/guides/10-advanced-typescript.md

• curried form 이유, middleware 타이핑, slices pattern 타입, mutator reference

Framework Integration

Next.js? → references/guides/12-nextjs.md

• per-request store, Context Provider, App Router / Pages Router

SSR and Hydration? → references/guides/13-ssr-and-hydration.md

• SSR 기본, hydration, hydration 에러 원인

Initialize state with props? → references/guides/14-initialize-state-with-props.md

• vanilla store + Context, Provider wrapper, custom hook

Miscellaneous

Connect to state with URL hash? → references/guides/07-connect-to-state-with-url-hash.md

• URL hash/query params와 상태 동기화

Event handler in pre-React 18? → references/guides/08-event-handler-in-pre-react-18.md

• unstable_batchedUpdates 워크어라운드

---

API Reference

APIs

create? → references/apis/01-create.md

• React Hook 생성, state 업데이트 패턴, subscribe

createStore? → references/apis/02-create-store.md

• vanilla store 생성, React 없이 사용

createWithEqualityFn? → references/apis/03-create-with-equality-fn.md

• 커스텀 equality 체크로 리렌더 최적화

shallow? → references/apis/04-shallow.md

• top-level shallow 비교, Object/Set/Map 비교

Hooks

useStore? → references/hooks/01-use-store.md

• vanilla store를 React에서 사용, global/scoped/dynamic 패턴

useStoreWithEqualityFn? → references/hooks/02-use-store-with-equality-fn.md

• 커스텀 equality 체크가 내장된 useStore

useShallow? → references/hooks/03-use-shallow.md

• selector 메모이제이션으로 리렌더 최적화

Middlewares

persist? → references/middlewares/01-persist.md

• localStorage/custom storage 영속화, partialize, versioning, migration, skipHydration

devtools? → references/middlewares/02-devtools.md

• Redux DevTools 연결, action naming, slices 디버깅

immer? → references/middlewares/03-immer.md

• mutation 문법으로 불변 업데이트

combine? → references/middlewares/04-combine.md

• 초기 상태와 actions 분리, 타입 자동 추론