React State Management

Priority: P0 (CRITICAL)

Choosing the right tool for state scope.

Implementation Guidelines

• Selection: Zustand for small-medium apps (minimal boilerplate, no Providers). Redux Toolkit (RTK) for large apps needing time-travel debugging or complex middleware.
• Server Data: Use React Query or SWR for server state. Never sync server data into useState manually. Let the cache be the source of truth.
• Context API: Use for low-frequency data like theme, auth, locale, or DI. Not for high-frequency updates (causes global re-renders). Split Context between State and Dispatch to optimize.
• Global Updates: Use Zustand, Jotai, or Redux for frequent/complex updates across the app.
• Local: useState for simple UI toggles. useReducer for complex state machines.
• Derived: Compute at render time (const fullName = ...). No useEffect to sync state.
• URL: Store filter/sort params in the URL Search Params (Single Source of Truth).
• Immutability: Never mutate. Use spread or Immer. Use useMemo on context value to prevent unnecessary re-renders (primitive performance tuning belongs in hooks skill).

Boundary note: hooks skill covers primitive API usage (useMemo, useCallback rules). This skill covers architectural state decisions — which tool to use for which state scope.

Reference & Examples

For Zustand, Redux Toolkit, and TanStack Query patterns: See references/REFERENCE.md.

Anti-Patterns

• No Context for High-Freq: Use Zustand/Redux for state that changes frequently.
• No State Sync: Compute derived values during render; avoid useEffect to sync state.
• No Server Cache as UI State: React Query/SWR for server data; don't duplicate into useState.