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