State Management

Modern state management patterns for React applications.

Decision Tree

User request → What type of state?
    │
    ├─ Client State (UI, local)
    │   ├─ Zustand → Simple, minimal boilerplate
    │   ├─ Jotai → Atomic, fine-grained
    │   ├─ Valtio → Proxy-based, mutable API
    │   └─ Context → Built-in, simple cases
    │
    ├─ Server State (API data)
    │   ├─ TanStack Query → Caching, background sync
    │   ├─ SWR → Lightweight, stale-while-revalidate
    │   └─ RTK Query → Redux ecosystem
    │
    ├─ Form State
    │   ├─ React Hook Form → Performance, validation
    │   ├─ Formik → Mature, feature-rich
    │   └─ Conform → Progressive enhancement
    │
    └─ URL State
        ├─ nuqs → Type-safe URL params
        └─ useSearchParams → Built-in Next.js

Quick Start

Zustand Setup

pnpm add zustand

// stores/useUserStore.ts
import { create } from "zustand";
import { persist, devtools } from "zustand/middleware";

interface User {
  id: string;
  email: string;
  name: string;
}

interface UserState {
  user: User | null;
  isAuthenticated: boolean;
  setUser: (user: User) => void;
  logout: () => void;
}

export const useUserStore = create<UserState>()(
  devtools(
    persist(
      (set) => ({
        user: null,
        isAuthenticated: false,
        setUser: (user) => set({ user, isAuthenticated: true }),
        logout: () => set({ user: null, isAuthenticated: false }),
      }),
      { name: "user-storage" }
    )
  )
);

TanStack Query Setup

pnpm add @tanstack/react-query @tanstack/react-query-devtools

// lib/query-client.ts
import { QueryClient } from "@tanstack/react-query";

export const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      staleTime: 60 * 1000, // 1 minute
      gcTime: 5 * 60 * 1000, // 5 minutes
      retry: 1,
      refetchOnWindowFocus: false,
    },
  },
});

// hooks/useUsers.ts
import { useQuery, useMutation, useQueryClient } from "@tanstack/react-query";
import { api } from "@/lib/api";

export function useUsers() {
  return useQuery({
    queryKey: ["users"],
    queryFn: () => api.get("/users"),
  });
}

export function useUser(id: string) {
  return useQuery({
    queryKey: ["users", id],
    queryFn: () => api.get(`/users/${id}`),
    enabled: !!id,
  });
}

export function useCreateUser() {
  const queryClient = useQueryClient();

  return useMutation({
    mutationFn: (data: CreateUserInput) => api.post("/users", data),
    onSuccess: () => {
      queryClient.invalidateQueries({ queryKey: ["users"] });
    },
  });
}

React Hook Form + Zod

pnpm add react-hook-form @hookform/resolvers zod

// components/UserForm.tsx
import { useForm } from "react-hook-form";
import { zodResolver } from "@hookform/resolvers/zod";
import { z } from "zod";

const userSchema = z.object({
  email: z.string().email("Invalid email"),
  name: z.string().min(2, "Name too short"),
  password: z.string().min(8, "Password must be 8+ characters"),
});

type UserFormData = z.infer<typeof userSchema>;

export function UserForm({ onSubmit }: { onSubmit: (data: UserFormData) => void }) {
  const {
    register,
    handleSubmit,
    formState: { errors, isSubmitting },
  } = useForm<UserFormData>({
    resolver: zodResolver(userSchema),
  });

  return (
    <form onSubmit={handleSubmit(onSubmit)}>
      <input {...register("email")} placeholder="Email" />
      {errors.email && <span>{errors.email.message}</span>}

      <input {...register("name")} placeholder="Name" />
      {errors.name && <span>{errors.name.message}</span>}

      <input {...register("password")} type="password" placeholder="Password" />
      {errors.password && <span>{errors.password.message}</span>}

      <button type="submit" disabled={isSubmitting}>
        {isSubmitting ? "Submitting..." : "Submit"}
      </button>
    </form>
  );
}

State Type Comparison

Reference Files

• Zustand Patterns: See references/zustand-patterns.md
• TanStack Query: See references/tanstack-query.md
• Form Patterns: See references/form-patterns.md

Best Practices

1. Separate concerns: UI state vs server state vs form state
2. Colocate state: Keep state close to where it's used
3. Derive don't duplicate: Compute values from source of truth
4. Normalize server data: Avoid nested structures
5. Optimistic updates: Instant feedback, rollback on error
6. Persist wisely: Only what's necessary
7. Type everything: Full TypeScript support
8. DevTools: Use in development for debugging