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