State Management Patterns

State Management Patterns

Battle-tested patterns for managing complex client state in React applications using Zustand, Jotai, and React Query. This collection covers the patterns that emerge when you move beyond simple useState — optimistic updates, cache synchronization, real-time data, and the hard decisions about where state actually belongs.

What's Inside

Zustand Patterns (`src/zustand/`)

• Store Slices — Split large stores into composable slices that share a single store instance. Includes typed slice creators and cross-slice communication.
• Middleware Stack — Logging, devtools integration, performance tracking, and immer middleware composed together.
• Persistence Layer — Storage adapters (localStorage, sessionStorage, IndexedDB) with migration support for evolving store shapes.

Jotai Patterns (`src/jotai/`)

• Atoms & Derived Atoms — Primitive atoms, computed atoms with selectors, and write-only atoms for complex updates.
• Async Atoms — Data fetching atoms with loading/error states, retry logic, and Suspense integration.
• Atom Families — Parameterized atoms for managing collections (e.g., per-item expanded state, per-tab filters).

React Query Patterns (`src/react-query/`)

• Query Patterns — Dependent queries, parallel queries, conditional fetching, and placeholder/initial data strategies.
• Mutations & Optimistic Updates — Mutation patterns with rollback, optimistic list updates, and toast notifications on failure.
• Infinite Queries — Cursor-based and offset-based infinite scroll with bi-directional support.
• Cache Invalidation — Granular invalidation, cache seeding from mutations, and stale-while-revalidate strategies.

Real-Time Sync (`src/realtime/`)

• WebSocket Integration — Reconnecting WebSocket manager that syncs server events into Zustand and React Query caches.
• Optimistic Updates — Shared patterns for optimistic UI across all three libraries, with server reconciliation.

Decision Guide (`guides/decision-guide.md`)

When should you reach for Zustand vs. Jotai vs. React Query? A decision tree based on the _shape_ of your state problem, not library popularity.

Working Examples (`examples/`)

• Todo app with Zustand (local-first with sync)
• Dashboard with Jotai (fine-grained reactivity)
• Data table with React Query (server state with filtering)

Quick Start

# Install the libraries you want to use (pick one or combine):
npm install zustand immer
npm install jotai
npm install @tanstack/react-query

# Copy the patterns you need into your project
cp -r src/zustand/ your-project/src/state/

Each pattern file is self-contained. Import what you need, ignore the rest.

File Structure

state-management-patterns/
├── README.md
├── LICENSE
├── tsconfig.json
├── src/
│   ├── zustand/
│   │   ├── store-slices.ts           # Composable store slices
│   │   ├── middleware.ts             # Custom middleware stack
│   │   └── persistence.ts           # Storage adapters & migrations

*... continues with setup instructions, usage examples, and more.*