State management: put each piece where it belongs

The only taxonomy that matters

Most "we need Redux" moments are really "our fetch cache and our UI state got tangled".

Server state ≠ client state

Server state has properties no client store models well: caching, invalidation, retries, race conditions, optimistic updates. Don't hand-roll these:

// ❌ hand-rolled cache
const [users, setUsers] = useState<User[]>([])
useEffect(() => { fetchUsers().then(setUsers) }, [])

// ✅ the cache handles dedupe/retry/race/invalidation
const { data: users } = useQuery({ queryKey: ['users'], queryFn: fetchUsers })

Rules:

1. Mutations invalidate keys, they don't patch arrays.
2. Optimistic update = apply → rollback on error → always reconcile with server response.
3. Track updatedAt; stale-while-revalidate is a feature, not a bug.

Colocate before you centralize

Lift state only when a second consumer appears. State used by one component lives in that component. A "global store" with 40% single-consumer keys is a symptom.

URL is state (the most forgotten one)

Filters, tabs, pagination, sort → search params. You get shareability, back button, and SSR for free; refresh preserves context.

const [params, setParams] = useSearchParams()
setParams({ tab: 'advanced', page: '2' })   // not useState('advanced')

Forms are their own domain

Controlled fields in local state (or a form library); never push keystrokes into a global store. Validation mirrors the server's contract; one source of truth for error shape.

Undo/redo

Only model it where the product needs it (editors, canvases): keep a past/present/future triple of the document state, commit at meaningful actions (not keystrokes), cap history depth.

When you do need a store

• Prefer signals/atoms-style libs (Zustand, Jotai, Pinia) over single-tree flux for new code.
• Selectors over subscriptions: components subscribe to slices, not the store; derived values are selectors/computed, never copied.
• One direction: actions mutate, components read. A store that both components write and components derive from in cycles is a design bug.

Definition of done (agent checklist)

• Server state lives in a query cache, not useEffect+setState
• Shareable view state (filters/tabs/page) is in the URL
• State colocated; store has no single-consumer keys
• No derived state kept in sync by effects
• Mutations invalidate; optimistic paths roll back