State Management Architect

State Categorization

Before choosing a library, classify every piece of state:

Rule: Use the right tool for each category

Server State (TanStack Query Pattern)

// Fetch with automatic caching, refetching, and loading states
const { data, isLoading, error } = useQuery({
  queryKey: ['users', userId],
  queryFn: () => api.getUser(userId),
  staleTime: 5 * 60 * 1000, // Consider fresh for 5 minutes
});

// Mutation with optimistic update
const mutation = useMutation({
  mutationFn: api.updateUser,
  onMutate: async (newData) => {
    await queryClient.cancelQueries({ queryKey: ['users', userId] });
    const previous = queryClient.getQueryData(['users', userId]);
    queryClient.setQueryData(['users', userId], newData);
    return { previous };
  },
  onError: (err, vars, ctx) => queryClient.setQueryData(['users', userId], ctx.previous),
  onSettled: () => queryClient.invalidateQueries({ queryKey: ['users', userId] }),
});

Client State (Zustand Pattern)

const useUIStore = create<UIState>((set) => ({
  sidebarOpen: false,
  theme: 'light',
  toggleSidebar: () => set((s) => ({ sidebarOpen: !s.sidebarOpen })),
  setTheme: (theme) => set({ theme }),
}));
// Usage: subscribe to slices — const open = useUIStore((s) => s.sidebarOpen);

URL State Pattern

// Filters and pagination belong in the URL, not in state
const [searchParams, setSearchParams] = useSearchParams();
const page = parseInt(searchParams.get('page') || '1', 10);
const sort = searchParams.get('sort') || 'newest';
const filter = searchParams.get('filter') || 'all';

Cache Invalidation Strategy

State Machine Pattern (Complex Flows)

For multi-step workflows (checkout, onboarding, file upload):

type UploadState =
  | { status: 'idle' }
  | { status: 'selecting' }
  | { status: 'uploading'; progress: number }
  | { status: 'processing' }
  | { status: 'complete'; url: string }
  | { status: 'error'; message: string };

Use discriminated unions to make invalid states unrepresentable.

Anti-Patterns

• Global state for everything (makes components impossible to test in isolation)
• Duplicating server data in client store (stale by definition)
• Prop drilling through 5+ levels (use composition or context for stable values)
• Context for frequently changing values (re-renders entire tree)
• Derived state stored separately (compute it from source, don't sync it)
• useEffect to sync state between two useState calls (combine into one state or use derived value)