zustand-patterns

name: zustand-patterns license: MIT compatibility: "Claude Code 2.1.277+." description: "Reference for Zustand 5.x state management including slices, middleware, Immer, useShallow, persistence, selectors, and devtools integration. Documents 7 core patterns with TypeScript examples and anti-patterns. Use when building React state management with Zustand instead of Redux." context: inherit allowed-tools: [Read, Write, Grep, Glob] user-invocable: false disable-model-invocation: true effort: low targets:

• library: zustand version: ">=5.0.0" model: haiku metadata: category: document-asset-creation version: "1.0.0" author: "OrchestKit" complexity: "low" tags: "zustand, state-management, react, immer, middleware, persistence, slices" path_patterns: ["/store/", "/stores/", ".store.", ".zustand."]

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.

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

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

• react-server-components-framework - RSC hydration considerations with Zustand
• Server state: https://tanstack.com/query/latest/docs/framework/react/guides/does-this-replace-client-state
• Form state: https://react-hook-form.com/docs/useform

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>"):

Other resources:

• Load: Read("scripts/store-template.ts") - Production-ready store template
• Load: Read("checklists/zustand-checklist.md") - Implementation checklist