---name: zustanddescription: Zustand state management best practices for React applications. Use when writing, reviewing, or refactoring Zustand stores to ensure optimal performance and maintainability. Triggers on tasks involving state management, stores, selectors, re-renders, and Zustand patterns.---

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