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

store-

select-

render-

update-

mw-

ssr-

ts-

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