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

Priority	Category	Impact	Prefix
1	Store Architecture	CRITICAL	store-
2	Selector Optimization	CRITICAL	select-
3	Re-render Prevention	HIGH	render-
4	State Updates	MEDIUM-HIGH	update-
5	Middleware Configuration	MEDIUM	mw-
6	SSR and Hydration	MEDIUM	ssr-
7	TypeScript Patterns	LOW-MEDIUM	ts-
8	Advanced Patterns	LOW	adv-

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

File	Description
references/_sections.md	Category definitions and ordering
assets/templates/_template.md	Template for new rules
metadata.json	Version and reference information