React State

Covers separating stores by domain (auth, cart, ui, theme) rather than one giant store, SOLID file organization (store.ts, store.interface.ts, use-store.ts), and forbidden patterns (persisting auth tokens, v4 syntax, skipping useShallow). This is the plain-React variant of Zustand (no App Router request-isolation concerns) — for Next.js App Router see nextjs-zustand, and for server state use TanStack Query instead of this skill.

Zustand for React

Minimal, scalable state management with React 18+ useSyncExternalStore.

Agent Workflow (MANDATORY)

Before ANY implementation, spawn 3 agents in parallel, one Agent call each with a name:

1. fuse-ai-pilot:explore-codebase - Analyze existing stores and state patterns
2. fuse-ai-pilot:research-expert - Verify latest Zustand v5 docs via Context7/Exa
3. mcp__context7__query-docs - Check middleware and TypeScript patterns

After implementation, run fuse-ai-pilot:sniper for validation.

Overview

When to Use

• Managing global state in React applications
• Need state shared across components
• Persisting state to localStorage/sessionStorage
• Building UI state (modals, sidebars, theme, cart)
• Replacing React Context for complex state

Why Zustand v5

Critical Rules

1. useShallow for arrays/objects - Prevent unnecessary re-renders
2. Currying syntax v5 - create<State>()((set) => ({...}))
3. SOLID paths - Stores in modules/[feature]/src/stores/
4. Separate stores - One store per domain (auth, cart, ui, theme)
5. Server state elsewhere - Use TanStack Query for server state

SOLID Architecture

Module Structure

Stores organized by feature module:

• modules/cores/stores/ - Shared stores (theme, ui)
• modules/auth/src/stores/ - Auth state
• modules/cart/src/stores/ - Cart state
• modules/[feature]/src/interfaces/ - Store types

File Organization

Key Concepts

Store Creation (v5 Syntax)

Double parentheses required for TypeScript inference. Currying pattern ensures full type safety.

Middleware Composition

Stack middlewares: devtools -> persist -> immer. Order matters for TypeScript types.

Selector Pattern

Always use useStore((s) => s.field) for performance. Use useShallow for array/object selectors.

Reference Guide

Best Practices

1. Selector pattern - Always use useStore((s) => s.field) for performance
2. useShallow - Wrap array/object selectors to prevent re-renders
3. Separate stores - One store per domain (auth, cart, ui, theme)
4. Server data elsewhere - Use TanStack Query for server state
5. DevTools in dev only - Wrap devtools in process.env check
6. Partialize persist - Only persist necessary fields, never tokens

Forbidden Patterns