Zustand

Community Zustand Best Practices

Comprehensive performance and architecture guide for Zustand state management in React applications. Contains 43 rules across 8 categories, prioritized by impact from critical (store architecture, selector optimization) to incremental (advanced patterns).

When to Apply

Reference these guidelines when:

• Creating new Zustand stores
• Optimizing re-render performance with selectors
• Implementing persistence or middleware
• Integrating Zustand with SSR/Next.js
• Reviewing code for state management patterns

Rule Categories by Priority

Quick Reference

1. Store Architecture (CRITICAL)

• `store-multiple-stores` - Use multiple small stores instead of one monolithic store
• `store-separate-actions` - Separate actions from state in dedicated namespace
• `store-event-naming` - Name actions as events not setters
• `store-colocate-logic` - Colocate actions with the state they modify
• `store-avoid-derived-state` - Derive computed values instead of storing them
• `store-domain-boundaries` - Organize stores by feature domain

2. Selector Optimization (CRITICAL)

• `select-always-use` - Always use selectors never subscribe to entire store
• `select-atomic-picks` - Use atomic selectors for single values
• `select-stable-returns` - Ensure selectors return stable references
• `select-custom-hooks` - Export custom hooks not raw store
• `select-auto-generate` - Use auto-generated selectors for large stores
• `select-memoize-computed` - Memoize expensive computed selectors
• `select-avoid-inline` - Define selectors outside components

3. Re-render Prevention (HIGH)

• `render-use-shallow` - Use useShallow for multi-property selections
• `render-equality-fn` - Provide custom equality functions when needed
• `render-memo-children` - Memo children affected by parent store updates
• `render-subscribe-external` - Use subscribe for non-React consumers
• `render-avoid-object-returns` - Avoid returning new objects from selectors
• `render-split-components` - Split components to minimize subscription scope

4. State Updates (MEDIUM-HIGH)

• `update-functional-set` - Use functional form when updating based on previous state
• `update-immutable` - Never mutate state directly
• `update-shallow-merge` - Understand set() shallow merge behavior
• `update-async-actions` - Handle async actions with loading and error states
• `update-batch-updates` - Batch related updates in single set call

5. Middleware Configuration (MEDIUM)

• `mw-devtools-actions` - Name actions for DevTools debugging
• `mw-persist-partialize` - Use partialize for selective persistence
• `mw-persist-migration` - Version and migrate persisted state
• `mw-immer-nested` - Use immer for deeply nested state updates
• `mw-combine-order` - Apply middlewares in correct order
• `mw-slice-middleware` - Apply middleware at combined store level

6. SSR and Hydration (MEDIUM)

• `ssr-skip-hydration` - Use skipHydration in SSR contexts
• `ssr-manual-rehydrate` - Manually rehydrate on client mount
• `ssr-hydration-hook` - Use custom hook to prevent hydration mismatch
• `ssr-check-window` - Guard browser APIs with typeof window check

7. TypeScript Patterns (LOW-MEDIUM)

• `ts-state-creator` - Use StateCreator for slice typing
• `ts-middleware-inference` - Preserve type inference with middleware
• `ts-separate-types` - Separate state and actions interfaces
• `ts-generic-selectors` - Type selectors for reusability
• `ts-bound-store` - Type combined stores correctly

8. Advanced Patterns (LOW)

• `adv-context-stores` - Combine Zustand with React Context for dependency injection
• `adv-transient-updates` - Use subscribe for transient updates
• `adv-computed-getters` - Implement computed state with getters
• `adv-third-party-integration` - Integrate with React Query and SWR

How to Use

Read individual reference files for detailed explanations and code examples:

• Section definitions - Category structure and impact levels
• Rule template - Template for adding new rules

Reference Files