state-management

State Management

Overview

Global client state and asynchronous server state architecture in modern React and Next.js applications using Zustand and TanStack Query v5.

When to Use

Activate when managing asynchronous server data fetching, HTTP caching, optimistic UI updates, or global synchronous client UI state (modals, active filters, multi-step wizards, theme overrides).

Rules & Patterns

The Rule of Two States

1. SERVER STATE (Async): Managed exclusively by TanStack Query (useQuery, useMutation). Handles HTTP caching, stale-while-revalidate, deduplication, background refetching, pagination, and query invalidation.
2. CLIENT STATE (Sync): Managed by Zustand. Handles transient UI state: modal visibility, sidebar collapsed state, active filter values, wizard steps, and offline draft buffers.

Negative Constraints (What NOT to Do)

1. NEVER store server-fetched entity data in Zustand or Redux: Store ONLY client-local UI state in Zustand. All API responses, lists, and entity records belong in TanStack Query.
2. NEVER duplicate derived state: Compute values inline or via useMemo from existing state instead of storing redundant state variables.
3. NEVER subscribe to entire store objects in components: Always use atomic selector functions (e.g. useStore(state => state.isOpen)) or useShallow to prevent unnecessary component re-renders.
4. NEVER mutate state directly: Always return new immutable state objects in Zustand setters.
5. NEVER ignore optimistic rollback on mutation failure: When implementing optimistic UI, always capture previousData in onMutate and restore it in onError.
6. NEVER use ad-hoc array strings for query keys: Always define and use a centralized Query Key Factory to guarantee consistent cache invalidation.

---

Pattern 1: Zustand Slices Architecture

Split large global stores into focused, typed slices that compose into a single unified hook:

import { create, StateCreator } from 'zustand';
import { devtools } from 'zustand/middleware';

interface UiSlice {
  isSidebarOpen: boolean;
  activeModal: string | null;
  toggleSidebar: () => void;
  openModal: (modalId: string) => void;
  closeModal: () => void;
}

const createUiSlice: StateCreator<UiSlice> = (set) => ({
  isSidebarOpen: true,
  activeModal: null,
  toggleSidebar: () => set((state) => ({ isSidebarOpen: !state.isSidebarOpen })),
  openModal: (modalId) => set({ activeModal: modalId }),
  closeModal: () => set({ activeModal: null }),
});

export const useAppStore = create<UiSlice>()(
  devtools((...args) => ({
    ...createUiSlice(...args),
  }))
);