react-state

# Zustand for React

Minimal, scalable state management with React 18+ useSyncExternalStore.

## Agent Workflow (MANDATORY)

Before ANY implementation, launch in parallel:

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

| Feature | Benefit |
|---------|---------|
| Minimal API | Simple create() function, no boilerplate |
| React 18 native | useSyncExternalStore, no shims needed |
| TypeScript first | Full inference with currying pattern |
| Middleware stack | devtools, persist, immer composable |
| Bundle size | ~2KB gzipped, smallest state library |
| No providers | Direct store access, no Context wrapper |

---

## 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

| File | Purpose | Max Lines |
|------|---------|-----------|
| `store.ts` | Store creation with create() | 50 |
| `store.interface.ts` | TypeScript interfaces | 30 |
|