Zustand Patterns
Modern state management with Zustand 5.x - lightweight, TypeScript-first, no boilerplate.
Overview
- Global state without Redux complexity
- Shared state across components without prop drilling
- Persisted state with localStorage/sessionStorage
- Computed/derived state with selectors
- State that needs middleware (logging, devtools, persistence)
Upstream coverage (do not restate)
Zustand's own docs are the source for the mechanics. This skill carries only the OrchestKit delta
on top of them, in references/ork-delta.md, the rules/ files, and the checklist.
| Topic |
First-party source |
Basic store, create<State>()(), actions, async actions |
https://github.com/pmndrs/zustand/blob/main/docs/reference/apis/create.md |
| Slices pattern (splitting and combining stores) |
https://github.com/pmndrs/zustand/blob/main/docs/learn/guides/slices-pattern.md |
| Typing slices and middleware mutator tuples |
https://github.com/pmndrs/zustand/blob/main/docs/learn/guides/advanced-typescript.md |
| Immer middleware (draft mutations) |
https://github.com/pmndrs/zustand/blob/main/docs/reference/middlewares/immer.md |
persist: partialize, version, migrate, onRehydrateStorage, storage adapters |
https://github.com/pmndrs/zustand/blob/main/docs/reference/middlewares/persist.md |
devtools: action names, enabled, serialize, trace |
https://github.com/pmndrs/zustand/blob/main/docs/reference/middlewares/devtools.md |
subscribeWithSelector and non-React subscriptions |
https://github.com/pmndrs/zustand/blob/main/docs/reference/middlewares/subscribe-with-selector.md |
Selectors and useShallow re-render control |
https://github.com/pmndrs/zustand/blob/main/docs/learn/guides/prevent-rerenders-with-use-shallow.md |
v4 to v5 migration (createWithEqualityFn, React 18 floor) |
https://github.com/pmndrs/zustand/blob/main/docs/reference/migrations/migrating-to-v5.md |
| SSR and hydration |
https://github.com/pmndrs/zustand/blob/main/docs/learn/guides/ssr-and-hydration.md |
| Store testing and reset |
https://github.com/pmndrs/zustand/blob/main/docs/learn/guides/testing.md |
| Server-state ownership (use TanStack Query, not Zustand) |
https://tanstack.com/query/latest/docs/framework/react/guides/does-this-replace-client-state |
Quick Reference
// ✅ Create typed store with double-call pattern
const useStore = create<State>()((set, get) => ({ ... }));
// ✅ Use selectors for all state access
const count = useStore((s) => s.count);
// ✅ Use useShallow for multiple values (Zustand 5.x)
const { a, b } = useStore(useShallow((s) => ({ a: s.a, b: s.b })));
// ✅ Middleware order: immer → subscribeWithSelector → devtools → persist
create(persist(devtools(immer((set) => ({ ... })))))
// ❌ Never destructure entire store
const store = useStore(); // Re-renders on ANY change
// ❌ Never store server state (use TanStack Query instead)
const useStore = create((set) => ({ users: [], fetchUsers: async () => ... }));
Key Decisions
| Decision |
Option A |
Option B |
Recommendation |
| State structure |
Single store |
Multiple stores |
Slices in single store - easier cross-slice access |
| Nested updates |
Spread operator |
Immer middleware |
Immer for deeply nested state (3+ levels) |
| Persistence |
Manual localStorage |
persist middleware |
persist middleware with partialize |
| Multiple values |
Multiple selectors |
useShallow |
useShallow for 2-5 related values |
| Server state |
Zustand |
TanStack Query |
TanStack Query - Zustand for client-only state |
| DevTools |
Always on |
Conditional |
Conditional - enabled: process.env.NODE_ENV === 'development' |
Anti-Patterns & Integration
Forbidden patterns (store destructuring, derived state, server state, direct mutation) and React Query integration guidance.
Load Read("references/anti-patterns-and-integration.md") for anti-pattern examples and TanStack Query separation patterns.
Related Skills
Capability Details
store-creation
Keywords: zustand, create, store, typescript, state
Solves: Setting up type-safe Zustand stores with proper TypeScript inference
slices-pattern
Keywords: slices, modular, split, combine, StateCreator
Solves: Organizing large stores into maintainable, domain-specific slices
middleware-stack
Keywords: immer, persist, devtools, middleware, compose
Solves: Combining middleware in correct order for immutability, persistence, and debugging
selector-optimization
Keywords: selector, useShallow, re-render, performance, memoization
Solves: Preventing unnecessary re-renders with proper selector patterns
persistence-migration
Keywords: persist, localStorage, sessionStorage, migrate, version
Solves: Persisting state with schema migrations between versions
References
Load on demand with Read("references/<file>"):
| File |
Content |
ork-delta.md |
OrchestKit-specific rules: the corrected zustand/shallow label, the v5 floor, secret handling, graded slice typing |
anti-patterns-and-integration.md |
Forbidden patterns and React Query integration |
Other resources:
- Load:
Read("scripts/store-template.ts") - Production-ready store template
- Load:
Read("checklists/zustand-checklist.md") - Implementation checklist
1---2name: zustand-patterns3license: MIT4compatibility: "Claude Code 2.1.277+."5description: "Zustand 5.x state management reference: slices, middleware, Immer, useShallow, persistence, selectors, devtools, with TypeScript examples. Use when building React state management with Zustand instead of Redux."6context: inherit7allowed-tools: "Read Write Grep Glob"8user-invocable: false9effort: low10targets:11 - library: zustand12 version: ">=5.0.0"13model: haiku14metadata:15 source: https://skillmd.com/skills/yonatangross/zustand-patterns16 category: document-asset-creation17 version: "1.0.0"18 author: "OrchestKit"19 complexity: "low"20 tags: "zustand, state-management, react, immer, middleware, persistence, slices"21path_patterns: ["**/store/**", "**/stores/**", "*.store.*", "*.zustand.*"]22---2324# Zustand Patterns2526Modern state management with Zustand 5.x - lightweight, TypeScript-first, no boilerplate.2728## Overview2930- Global state without Redux complexity31- Shared state across components without prop drilling32- Persisted state with localStorage/sessionStorage33- Computed/derived state with selectors34- State that needs middleware (logging, devtools, persistence)3536## Upstream coverage (do not restate)3738Zustand's own docs are the source for the mechanics. This skill carries only the OrchestKit delta39on top of them, in `references/ork-delta.md`, the `rules/` files, and the checklist.4041| Topic | First-party source |42|-------|--------------------|43| Basic store, `create<State>()()`, actions, async actions | https://github.com/pmndrs/zustand/blob/main/docs/reference/apis/create.md |44| Slices pattern (splitting and combining stores) | https://github.com/pmndrs/zustand/blob/main/docs/learn/guides/slices-pattern.md |45| Typing slices and middleware mutator tuples | https://github.com/pmndrs/zustand/blob/main/docs/learn/guides/advanced-typescript.md |46| Immer middleware (draft mutations) | https://github.com/pmndrs/zustand/blob/main/docs/reference/middlewares/immer.md |47| persist: `partialize`, `version`, `migrate`, `onRehydrateStorage`, storage adapters | https://github.com/pmndrs/zustand/blob/main/docs/reference/middlewares/persist.md |48| devtools: action names, `enabled`, `serialize`, `trace` | https://github.com/pmndrs/zustand/blob/main/docs/reference/middlewares/devtools.md |49| `subscribeWithSelector` and non-React subscriptions | https://github.com/pmndrs/zustand/blob/main/docs/reference/middlewares/subscribe-with-selector.md |50| Selectors and `useShallow` re-render control | https://github.com/pmndrs/zustand/blob/main/docs/learn/guides/prevent-rerenders-with-use-shallow.md |51| v4 to v5 migration (`createWithEqualityFn`, React 18 floor) | https://github.com/pmndrs/zustand/blob/main/docs/reference/migrations/migrating-to-v5.md |52| SSR and hydration | https://github.com/pmndrs/zustand/blob/main/docs/learn/guides/ssr-and-hydration.md |53| Store testing and reset | https://github.com/pmndrs/zustand/blob/main/docs/learn/guides/testing.md |54| Server-state ownership (use TanStack Query, not Zustand) | https://tanstack.com/query/latest/docs/framework/react/guides/does-this-replace-client-state |5556## Quick Reference5758```typescript59// ✅ Create typed store with double-call pattern60const useStore = create<State>()((set, get) => ({ ... }));6162// ✅ Use selectors for all state access63const count = useStore((s) => s.count);6465// ✅ Use useShallow for multiple values (Zustand 5.x)66const { a, b } = useStore(useShallow((s) => ({ a: s.a, b: s.b })));6768// ✅ Middleware order: immer → subscribeWithSelector → devtools → persist69create(persist(devtools(immer((set) => ({ ... })))))7071// ❌ Never destructure entire store72const store = useStore(); // Re-renders on ANY change7374// ❌ Never store server state (use TanStack Query instead)75const useStore = create((set) => ({ users: [], fetchUsers: async () => ... }));76```7778## Key Decisions7980| Decision | Option A | Option B | Recommendation |81|----------|----------|----------|----------------|82| State structure | Single store | Multiple stores | **Slices in single store** - easier cross-slice access |83| Nested updates | Spread operator | Immer middleware | **Immer** for deeply nested state (3+ levels) |84| Persistence | Manual localStorage | persist middleware | **persist middleware** with partialize |85| Multiple values | Multiple selectors | useShallow | **useShallow** for 2-5 related values |86| Server state | Zustand | TanStack Query | **TanStack Query** - Zustand for client-only state |87| DevTools | Always on | Conditional | **Conditional** - `enabled: process.env.NODE_ENV === 'development'` |8889## Anti-Patterns & Integration9091Forbidden patterns (store destructuring, derived state, server state, direct mutation) and React Query integration guidance.9293Load Read("references/anti-patterns-and-integration.md") for anti-pattern examples and TanStack Query separation patterns.9495## Related Skills9697- `react-server-components-framework` - RSC hydration considerations with Zustand98- Server state: https://tanstack.com/query/latest/docs/framework/react/guides/does-this-replace-client-state99- Form state: https://react-hook-form.com/docs/useform100101## Capability Details102103### store-creation104**Keywords**: zustand, create, store, typescript, state105**Solves**: Setting up type-safe Zustand stores with proper TypeScript inference106107### slices-pattern108**Keywords**: slices, modular, split, combine, StateCreator109**Solves**: Organizing large stores into maintainable, domain-specific slices110111### middleware-stack112**Keywords**: immer, persist, devtools, middleware, compose113**Solves**: Combining middleware in correct order for immutability, persistence, and debugging114115### selector-optimization116**Keywords**: selector, useShallow, re-render, performance, memoization117**Solves**: Preventing unnecessary re-renders with proper selector patterns118119### persistence-migration120**Keywords**: persist, localStorage, sessionStorage, migrate, version121**Solves**: Persisting state with schema migrations between versions122123## References124125Load on demand with `Read("references/<file>")`:126127| File | Content |128|------|---------|129| `ork-delta.md` | OrchestKit-specific rules: the corrected `zustand/shallow` label, the v5 floor, secret handling, graded slice typing |130| `anti-patterns-and-integration.md` | Forbidden patterns and React Query integration |131132Other resources:133- Load: `Read("scripts/store-template.ts")` - Production-ready store template134- Load: `Read("checklists/zustand-checklist.md")` - Implementation checklist