Zustand State Management
Overview
Zustand v5 is a lightweight global state manager for React built on useSyncExternalStore. Requires React 18+ (uses useSyncExternalStore internally). When using createWithEqualityFn, install use-sync-external-store as a peer dependency. It provides type-safe stores, atomic selectors for minimal re-renders, composable middleware (persist, devtools, immer, subscribeWithSelector), and a slices pattern for large applications. Use Zustand for client-only global state; use TanStack Query for server-fetched data.
When to use: Client-side global state, persistent user preferences, complex multi-domain stores, cross-component state sharing, vanilla (non-React) state management.
When NOT to use: Server state with caching needs (use TanStack Query), single-component state (use useState), simple prop drilling scenarios.
Quick Reference
| Pattern |
API |
Key Points |
| Basic store |
create<T>()((set) => ({...})) |
Double parentheses required for TS |
| Atomic selector |
useStore(state => state.bears) |
Only re-renders when selected value changes |
| Multiple values |
useShallow(state => ({a, b})) |
Import from zustand/react/shallow |
| Persist |
persist(fn, { name }) |
localStorage with SSR hydration handling |
| Devtools |
devtools(fn, { name }) |
Redux DevTools integration |
| SubscribeWithSelector |
subscribeWithSelector(fn) |
Subscribe to state slices outside React |
| Middleware order |
devtools(persist(fn)) |
Outer to inner wrapping |
| Slices pattern |
StateCreator<Combined, [], [], Slice> |
Split store by domain |
| SSR provider |
createStore + React Context |
Per-request stores prevent data leaks |
| Immer |
immer(fn) |
Safe nested state mutations |
| Vanilla store |
createStore from zustand/vanilla |
Use outside React |
| Reset store |
set(store.getInitialState()) |
Use getInitialState() for reliable reset |
| Derived values |
useStore(s => s.items.length) |
Compute in selector |
| Auto selectors |
createSelectors(store) |
Generate store.use.field() hooks automatically |
Common Mistakes
| Mistake |
Correct Pattern |
Using create<T>(...) with single parentheses |
Use create<T>()(...) double parentheses for correct TypeScript middleware inference |
Selecting full state object with useStore(state => state) |
Use atomic selectors like state.bears or useShallow to avoid unnecessary re-renders |
Importing useShallow from zustand/shallow |
Import from zustand/react/shallow; zustand/shallow exports the plain shallow function only |
| Creating new object references in selectors causing infinite loops |
Use separate primitive selectors or wrap with useShallow from zustand/react/shallow |
| Using a global singleton store with SSR or Next.js |
Use the StoreContext provider pattern with createStore to prevent data leaks between requests |
| Tracking initial state manually for reset |
Use store.getInitialState() which Zustand provides automatically |
| Using Zustand for server-fetched data that needs caching and revalidation |
Use TanStack Query for server state; reserve Zustand for client-only global state |
Delegation
- Store architecture and slices design: Use
Plan agent to define domain boundaries, slice interfaces, and middleware composition order
- Hydration and SSR debugging: Use
Task agent to diagnose persist middleware issues, hydration mismatches, and Next.js provider setup
- Migration from v4 to v5: Use
Explore agent to find deprecated import paths, single-parentheses patterns, and legacy middleware usage
- Testing strategy: Use
Task agent to set up store mocks and test isolation patterns
References
- Store patterns, TypeScript, and core API
- Middleware: persist, devtools, immer, subscribeWithSelector, and custom
- Slices pattern and large store architecture
- SSR, Next.js, and hydration handling
- Testing stores with Vitest and Jest
- Migration guide: Redux, Context, and v4 to v5
1---2name: zustand3description: Zustand v5 state management for React. Covers TypeScript stores with double-parentheses syntax, persist middleware with hydration handling, devtools, subscribeWithSelector, slices pattern for large apps, SSR/Next.js provider pattern, immer middleware, auto-generating selectors, testing, and vanilla stores. Use when setting up global state, configuring persist middleware, implementing slices pattern, migrating from Redux or Context, testing stores, or troubleshooting hydration and TypeScript issues.4license: MIT5---6
7# Zustand State Management
8
9## Overview
10
11Zustand v5 is a lightweight global state manager for React built on `useSyncExternalStore`. Requires React 18+ (uses `useSyncExternalStore` internally). When using `createWithEqualityFn`, install `use-sync-external-store` as a peer dependency. It provides type-safe stores, atomic selectors for minimal re-renders, composable middleware (persist, devtools, immer, subscribeWithSelector), and a slices pattern for large applications. Use Zustand for client-only global state; use TanStack Query for server-fetched data.
12
13**When to use:** Client-side global state, persistent user preferences, complex multi-domain stores, cross-component state sharing, vanilla (non-React) state management.
14
15**When NOT to use:** Server state with caching needs (use TanStack Query), single-component state (use useState), simple prop drilling scenarios.
16
17## Quick Reference
18
19| Pattern | API | Key Points |
20| --------------------- | --------------------------------------- | ------------------------------------------------ |
21| Basic store | `create<T>()((set) => ({...}))` | Double parentheses required for TS |
22| Atomic selector | `useStore(state => state.bears)` | Only re-renders when selected value changes |
23| Multiple values | `useShallow(state => ({a, b}))` | Import from `zustand/react/shallow` |
24| Persist | `persist(fn, { name })` | localStorage with SSR hydration handling |
25| Devtools | `devtools(fn, { name })` | Redux DevTools integration |
26| SubscribeWithSelector | `subscribeWithSelector(fn)` | Subscribe to state slices outside React |
27| Middleware order | `devtools(persist(fn))` | Outer to inner wrapping |
28| Slices pattern | `StateCreator<Combined, [], [], Slice>` | Split store by domain |
29| SSR provider | `createStore` + React Context | Per-request stores prevent data leaks |
30| Immer | `immer(fn)` | Safe nested state mutations |
31| Vanilla store | `createStore` from `zustand/vanilla` | Use outside React |
32| Reset store | `set(store.getInitialState())` | Use `getInitialState()` for reliable reset |
33| Derived values | `useStore(s => s.items.length)` | Compute in selector |
34| Auto selectors | `createSelectors(store)` | Generate `store.use.field()` hooks automatically |
35
36## Common Mistakes
37
38| Mistake | Correct Pattern |
39| ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
40| Using `create<T>(...)` with single parentheses | Use `create<T>()(...)` double parentheses for correct TypeScript middleware inference |
41| Selecting full state object with `useStore(state => state)` | Use atomic selectors like `state.bears` or `useShallow` to avoid unnecessary re-renders |
42| Importing `useShallow` from `zustand/shallow` | Import from `zustand/react/shallow`; `zustand/shallow` exports the plain `shallow` function only |
43| Creating new object references in selectors causing infinite loops | Use separate primitive selectors or wrap with `useShallow` from `zustand/react/shallow` |
44| Using a global singleton store with SSR or Next.js | Use the `StoreContext` provider pattern with `createStore` to prevent data leaks between requests |
45| Tracking initial state manually for reset | Use `store.getInitialState()` which Zustand provides automatically |
46| Using Zustand for server-fetched data that needs caching and revalidation | Use TanStack Query for server state; reserve Zustand for client-only global state |
47
48## Delegation
49
50- **Store architecture and slices design**: Use `Plan` agent to define domain boundaries, slice interfaces, and middleware composition order
51- **Hydration and SSR debugging**: Use `Task` agent to diagnose persist middleware issues, hydration mismatches, and Next.js provider setup
52- **Migration from v4 to v5**: Use `Explore` agent to find deprecated import paths, single-parentheses patterns, and legacy middleware usage
53- **Testing strategy**: Use `Task` agent to set up store mocks and test isolation patterns
54
55## References
56
57- [Store patterns, TypeScript, and core API](references/store-patterns.md)
58- [Middleware: persist, devtools, immer, subscribeWithSelector, and custom](references/middleware.md)
59- [Slices pattern and large store architecture](references/slices-pattern.md)
60- [SSR, Next.js, and hydration handling](references/ssr-hydration.md)
61- [Testing stores with Vitest and Jest](references/testing.md)
62- [Migration guide: Redux, Context, and v4 to v5](references/migration.md)
oakoss