Zustand Patterns

Zustand Patterns

Modern state management with Zustand 5.x - lightweight, TypeScript-first, no boilerplate.

Overview

• Global state without Redux complexity
• Shared state across components without prop drilling
• Persisted state with localStorage/sessionStorage
• Computed/derived state with selectors
• State that needs middleware (logging, devtools, persistence)

Core Patterns

Covers basic stores, slices, Immer, persist, selectors, async actions, and devtools.

Load Read("${CLAUDE_SKILL_DIR}/references/core-patterns.md") for full code examples of all 7 core patterns.

Quick Reference

// ✅ Create typed store with double-call pattern
const useStore = create<State>()((set, get) => ({ ... }));

// ✅ Use selectors for all state access
const count = useStore((s) => s.count);

// ✅ Use useShallow for multiple values (Zustand 5.x)
const { a, b } = useStore(useShallow((s) => ({ a: s.a, b: s.b })));

// ✅ Middleware order: immer → subscribeWithSelector → devtools → persist
create(persist(devtools(immer((set) => ({ ... })))))

// ❌ Never destructure entire store
const store = useStore(); // Re-renders on ANY change

// ❌ Never store server state (use TanStack Query instead)
const useStore = create((set) => ({ users: [], fetchUsers: async () => ... }));

Key Decisions

Anti-Patterns & Integration

Forbidden patterns (store destructuring, derived state, server state, direct mutation) and React Query integration guidance.

Load Read("${CLAUDE_SKILL_DIR}/references/anti-patterns-and-integration.md") for anti-pattern examples and TanStack Query separation patterns.

Related Skills

• tanstack-query-advanced - Server state management (use with Zustand for client state)
• form-state-patterns - Form state (React Hook Form vs Zustand for forms)
• react-server-components-framework - RSC hydration considerations with Zustand

Capability Details

store-creation

Keywords: zustand, create, store, typescript, state Solves: Setting up type-safe Zustand stores with proper TypeScript inference

slices-pattern

Keywords: slices, modular, split, combine, StateCreator Solves: Organizing large stores into maintainable, domain-specific slices

middleware-stack

Keywords: immer, persist, devtools, middleware, compose Solves: Combining middleware in correct order for immutability, persistence, and debugging

selector-optimization

Keywords: selector, useShallow, re-render, performance, memoization Solves: Preventing unnecessary re-renders with proper selector patterns

persistence-migration

Keywords: persist, localStorage, sessionStorage, migrate, version Solves: Persisting state with schema migrations between versions

References

Load on demand with Read("${CLAUDE_SKILL_DIR}/references/<file>"):

Other resources:

• Load: Read("${CLAUDE_SKILL_DIR}/scripts/store-template.ts") - Production-ready store template
• Load: Read("${CLAUDE_SKILL_DIR}/checklists/zustand-checklist.md") - Implementation checklist

Zustand Implementation Checklist

Comprehensive checklist for production-ready Zustand stores.

Store Setup

TypeScript Configuration

• [ ] Store interface defined with all state and actions
• [ ] create<State>()() double-call pattern used for type inference
• [ ] Action return types are void (mutations via set())
• [ ] type {} from '@redux-devtools/extension' imported for devtools typing

Store Structure

• [ ] Single store with slices (not multiple separate stores)
• [ ] Each slice has single responsibility (auth, cart, ui, etc.)
• [ ] Initial state extracted to const for reset functionality
• [ ] Reset action implemented for testing/logout

Middleware Stack

• [ ] Middleware applied in correct order: persist(devtools(subscribeWithSelector(immer(...))))
• [ ] Immer used if nested state updates needed (3+ levels deep)
• [ ] DevTools enabled for development only
• [ ] DevTools has meaningful store name

Selectors

Basic Selectors

• [ ] Every state access uses a selector
• [ ] No full-store destructuring: const { x, y } = useStore() ❌
• [ ] Selectors are granular (one value per selector when possible)

Multi-Value Selectors

• [ ] useShallow used for selecting multiple related values
• [ ] Import useShallow from zustand/shallow (the v5 migration-guide path)
• [ ] Deprecated: passing an equality fn to create() — migrate to createWithEqualityFn from zustand/traditional

Computed Values

• [ ] Derived state computed in selectors, not stored
• [ ] Expensive computations memoized with useMemo if needed

Action Selectors

• [ ] Action selectors exported for stable references
• [ ] Actions grouped by domain: useAuthActions(), useCartActions()

Persistence

Configuration

• [ ] partialize used to persist only necessary fields
• [ ] Ephemeral state excluded (loading, errors, UI toggles)
• [ ] Storage key is unique and descriptive

Migrations

• [ ] version field set (start at 1)
• [ ] migrate function handles all version transitions
• [ ] Migrations are tested
• [ ] onRehydrateStorage handles errors gracefully

Storage Selection

• [ ] localStorage for cross-tab persistence
• [ ] sessionStorage for tab-scoped persistence
• [ ] IndexedDB for large data (via idb-keyval)

DevTools

Configuration

• [ ] DevTools disabled in production: enabled: process.env.NODE_ENV === 'development'
• [ ] Store has descriptive name
• [ ] Sensitive data sanitized in serialize config

Action Naming

• [ ] All set() calls include action name: set(fn, undefined, 'domain/action')
• [ ] Action names follow convention: domain/action or domain/sub/action
• [ ] No anonymous actions in devtools timeline

Performance

Re-render Prevention

• [ ] Components only subscribe to needed state
• [ ] Large lists use virtualization
• [ ] Expensive selectors memoized

Bundle Size

• [ ] Tree-shaking works (check bundle analyzer)
• [ ] Unused middleware not imported

Testing

Test Setup

• [ ] Store can be reset between tests
• [ ] getState() used for assertions
• [ ] setState() used for test setup

Test Coverage

• [ ] All actions tested
• [ ] Selector outputs verified
• [ ] Persistence/rehydration tested
• [ ] Migrations tested with old state snapshots

Integration

React Query Separation

• [ ] Server state in React Query (API data)
• [ ] Client state in Zustand (UI, preferences)
• [ ] No API calls in Zustand actions (use React Query mutations)

SSR/RSC Considerations

• [ ] Hydration mismatch handled
• [ ] useStore only called in client components
• [ ] Initial state matches server render

Code Organization

File Structure

stores/
├── index.ts           # Re-exports
├── app-store.ts       # Main store with all slices
├── slices/
│   ├── auth-slice.ts
│   ├── cart-slice.ts
│   └── ui-slice.ts
├── selectors/
│   └── index.ts       # All selector exports
└── types.ts           # Shared types

Naming Conventions

• [ ] Store hook: useAppStore, useAuthStore
• [ ] Selectors: useUser, useCartItems, useTheme
• [ ] Action selectors: useAuthActions, useCartActions
• [ ] Slices: createAuthSlice, createCartSlice

Security

• [ ] No sensitive data in persisted state (tokens, passwords)
• [ ] DevTools sanitizes sensitive fields
• [ ] Auth tokens stored in memory-only slice or secure storage

Documentation

• [ ] Store interface documented with JSDoc
• [ ] Complex actions have usage examples
• [ ] Migration history documented
• [ ] README explains store architecture

Zustand Real-World Examples

Production-tested patterns for common use cases.

E-Commerce Cart Store

Complete shopping cart with persistence, optimistic updates, and computed totals.

import { create } from 'zustand';
import { persist, createJSONStorage } from 'zustand/middleware';
import { immer } from 'zustand/middleware/immer';

interface CartItem {
  id: string;
  productId: string;
  name: string;
  price: number;
  quantity: number;
  image: string;
}

interface CartState {
  items: CartItem[];
  addItem: (item: Omit<CartItem, 'id'>) => void;
  removeItem: (id: string) => void;
  updateQuantity: (id: string, quantity: number) => void;
  clearCart: () => void;
}

export const useCartStore = create<CartState>()(
  persist(
    immer((set) => ({
      items: [],

      addItem: (item) =>
        set((state) => {
          const existing = state.items.find((i) => i.productId === item.productId);
          if (existing) {
            existing.quantity += item.quantity;
          } else {
            state.items.push({ ...item, id: crypto.randomUUID() });
          }
        }),

      removeItem: (id) =>
        set((state) => {
          state.items = state.items.filter((i) => i.id !== id);
        }),

      updateQuantity: (id, quantity) =>
        set((state) => {
          const item = state.items.find((i) => i.id === id);
          if (item) {
            item.quantity = Math.max(0, quantity);
            if (item.quantity === 0) {
              state.items = state.items.filter((i) => i.id !== id);
            }
          }
        }),

      clearCart: () => set({ items: [] }),
    })),
    {
      name: 'cart-storage',
      storage: createJSONStorage(() => localStorage),
    }
  )
);

// ✅ Computed selectors (not stored state)
export const useCartItemCount = () =>
  useCartStore((s) => s.items.reduce((sum, item) => sum + item.quantity, 0));

export const useCartSubtotal = () =>
  useCartStore((s) => s.items.reduce((sum, item) => sum + item.price * item.quantity, 0));

export const useCartTax = () => {
  const subtotal = useCartSubtotal();
  return subtotal * 0.1; // 10% tax
};

export const useCartTotal = () => {
  const subtotal = useCartSubtotal();
  const tax = useCartTax();
  return subtotal + tax;
};

// Usage in component
function CartSummary() {
  const itemCount = useCartItemCount();
  const subtotal = useCartSubtotal();
  const tax = useCartTax();
  const total = useCartTotal();

  return (
    <div>
      <p>{itemCount} items</p>
      <p>Subtotal: ${subtotal.toFixed(2)}</p>
      <p>Tax: ${tax.toFixed(2)}</p>
      <p>Total: ${total.toFixed(2)}</p>
    </div>
  );
}

Authentication Store with Token Refresh

Auth state with automatic token refresh and secure handling.

import { create } from 'zustand';
import { subscribeWithSelector } from 'zustand/middleware';

interface User {
  id: string;
  email: string;
  name: string;
  role: 'user' | 'admin';
}

interface AuthState {
  user: User | null;
  accessToken: string | null;
  refreshToken: string | null;
  isAuthenticated: boolean;
  isLoading: boolean;

  login: (email: string, password: string) => Promise<void>;
  logout: () => void;
  refreshAuth: () => Promise<void>;
  setUser: (user: User) => void;
}

export const useAuthStore = create<AuthState>()(
  subscribeWithSelector((set, get) => ({
    user: null,
    accessToken: null,
    refreshToken: null,
    isAuthenticated: false,
    isLoading: false,

    login: async (email, password) => {
      set({ isLoading: true });
      try {
        const response = await fetch('/api/auth/login', {
          method: 'POST',
          headers: { 'Content-Type': 'application/json' },
          body: JSON.stringify({ email, password }),
        });

        if (!response.ok) throw new Error('Login failed');

        const { user, accessToken, refreshToken } = await response.json();

        set({
          user,
          accessToken,
          refreshToken,
          isAuthenticated: true,
          isLoading: false,
        });
      } catch (error) {
        set({ isLoading: false });
        throw error;
      }
    },

    logout: () => {
      set({
        user: null,
        accessToken: null,
        refreshToken: null,
        isAuthenticated: false,
      });
    },

    refreshAuth: async () => {
      const { refreshToken } = get();
      if (!refreshToken) {
        get().logout();
        return;
      }

      try {
        const response = await fetch('/api/auth/refresh', {
          method: 'POST',
          headers: { 'Content-Type': 'application/json' },
          body: JSON.stringify({ refreshToken }),
        });

        if (!response.ok) {
          get().logout();
          return;
        }

        const { accessToken, refreshToken: newRefreshToken } = await response.json();

        set({
          accessToken,
          refreshToken: newRefreshToken,
        });
      } catch {
        get().logout();
      }
    },

    setUser: (user) => set({ user }),
  }))
);

// ✅ Auto-refresh token before expiry
if (typeof window !== 'undefined') {
  useAuthStore.subscribe(
    (state) => state.accessToken,
    (accessToken) => {
      if (accessToken) {
        // Decode JWT to get expiry (simplified)
        const payload = JSON.parse(atob(accessToken.split('.')[1]));
        const expiresAt = payload.exp * 1000;
        const refreshAt = expiresAt - 60000; // Refresh 1 min before expiry

        const timeout = setTimeout(() => {
          useAuthStore.getState().refreshAuth();
        }, refreshAt - Date.now());

        return () => clearTimeout(timeout);
      }
    }
  );
}

// ✅ Selectors
export const useUser = () => useAuthStore((s) => s.user);
export const useIsAuthenticated = () => useAuthStore((s) => s.isAuthenticated);
export const useIsAdmin = () => useAuthStore((s) => s.user?.role === 'admin');
export const useAccessToken = () => useAuthStore((s) => s.accessToken);

Theme Store with System Preference Sync

Theme management that syncs with system preferences.

import { create } from 'zustand';
import { persist, createJSONStorage } from 'zustand/middleware';
import { subscribeWithSelector } from 'zustand/middleware';

type Theme = 'light' | 'dark' | 'system';
type ResolvedTheme = 'light' | 'dark';

interface ThemeState {
  theme: Theme;
  resolvedTheme: ResolvedTheme;
  setTheme: (theme: Theme) => void;
}

const getSystemTheme = (): ResolvedTheme =>
  typeof window !== 'undefined' &&
  window.matchMedia('(prefers-color-scheme: dark)').matches
    ? 'dark'
    : 'light';

const resolveTheme = (theme: Theme): ResolvedTheme =>
  theme === 'system' ? getSystemTheme() : theme;

export const useThemeStore = create<ThemeState>()(
  persist(
    subscribeWithSelector((set) => ({
      theme: 'system',
      resolvedTheme: getSystemTheme(),

      setTheme: (theme) =>
        set({
          theme,
          resolvedTheme: resolveTheme(theme),
        }),
    })),
    {
      name: 'theme-storage',
      storage: createJSONStorage(() => localStorage),
      partialize: (state) => ({ theme: state.theme }), // Only persist preference
      onRehydrateStorage: () => (state) => {
        // Resolve theme after hydration
        if (state) {
          state.resolvedTheme = resolveTheme(state.theme);
        }
      },
    }
  )
);

// ✅ Sync with system preference changes
if (typeof window !== 'undefined') {
  const mediaQuery = window.matchMedia('(prefers-color-scheme: dark)');

  mediaQuery.addEventListener('change', () => {
    const { theme } = useThemeStore.getState();
    if (theme === 'system') {
      useThemeStore.setState({ resolvedTheme: getSystemTheme() });
    }
  });

  // Apply theme to document
  useThemeStore.subscribe(
    (state) => state.resolvedTheme,
    (resolvedTheme) => {
      document.documentElement.classList.remove('light', 'dark');
      document.documentElement.classList.add(resolvedTheme);
    },
    { fireImmediately: true }
  );
}

// ✅ Selectors
export const useTheme = () => useThemeStore((s) => s.theme);
export const useResolvedTheme = () => useThemeStore((s) => s.resolvedTheme);
export const useIsDarkMode = () => useThemeStore((s) => s.resolvedTheme === 'dark');

Multi-Step Form Wizard Store

Form wizard with step validation and draft persistence.

import { create } from 'zustand';
import { persist, createJSONStorage } from 'zustand/middleware';
import { immer } from 'zustand/middleware/immer';

interface PersonalInfo {
  firstName: string;
  lastName: string;
  email: string;
}

interface AddressInfo {
  street: string;
  city: string;
  state: string;
  zip: string;
}

interface PaymentInfo {
  cardNumber: string;
  expiryDate: string;
  cvv: string;
}

interface WizardState {
  currentStep: number;
  personal: Partial<PersonalInfo>;
  address: Partial<AddressInfo>;
  payment: Partial<PaymentInfo>;
  completedSteps: Set<number>;

  setStep: (step: number) => void;
  nextStep: () => void;
  prevStep: () => void;
  updatePersonal: (data: Partial<PersonalInfo>) => void;
  updateAddress: (data: Partial<AddressInfo>) => void;
  updatePayment: (data: Partial<PaymentInfo>) => void;
  markStepComplete: (step: number) => void;
  reset: () => void;
}

const TOTAL_STEPS = 3;

const initialState = {
  currentStep: 0,
  personal: {},
  address: {},
  payment: {},
  completedSteps: new Set<number>(),
};

export const useWizardStore = create<WizardState>()(
  persist(
    immer((set) => ({
      ...initialState,

      setStep: (step) =>
        set((state) => {
          if (step >= 0 && step < TOTAL_STEPS) {
            state.currentStep = step;
          }
        }),

      nextStep: () =>
        set((state) => {
          if (state.currentStep < TOTAL_STEPS - 1) {
            state.currentStep += 1;
          }
        }),

      prevStep: () =>
        set((state) => {
          if (state.currentStep > 0) {
            state.currentStep -= 1;
          }
        }),

      updatePersonal: (data) =>
        set((state) => {
          Object.assign(state.personal, data);
        }),

      updateAddress: (data) =>
        set((state) => {
          Object.assign(state.address, data);
        }),

      updatePayment: (data) =>
        set((state) => {
          Object.assign(state.payment, data);
        }),

      markStepComplete: (step) =>
        set((state) => {
          state.completedSteps.add(step);
        }),

      reset: () => set(initialState),
    })),
    {
      name: 'wizard-draft',
      storage: createJSONStorage(() => sessionStorage), // Tab-scoped
      partialize: (state) => ({
        currentStep: state.currentStep,
        personal: state.personal,
        address: state.address,
        // Don't persist payment info for security
      }),
    }
  )
);

// ✅ Selectors
export const useCurrentStep = () => useWizardStore((s) => s.currentStep);
export const useIsFirstStep = () => useWizardStore((s) => s.currentStep === 0);
export const useIsLastStep = () => useWizardStore((s) => s.currentStep === TOTAL_STEPS - 1);
export const useWizardProgress = () => useWizardStore((s) => ((s.currentStep + 1) / TOTAL_STEPS) * 100);

Notification Toast Store

Global notification system with auto-dismiss.

import { create } from 'zustand';
import { immer } from 'zustand/middleware/immer';

type NotificationType = 'info' | 'success' | 'warning' | 'error';

interface Notification {
  id: string;
  type: NotificationType;
  title: string;
  message?: string;
  duration?: number;
  dismissible?: boolean;
}

interface NotificationState {
  notifications: Notification[];
  add: (notification: Omit<Notification, 'id'>) => string;
  remove: (id: string) => void;
  clear: () => void;
}

const DEFAULT_DURATION = 5000;

export const useNotificationStore = create<NotificationState>()(
  immer((set, get) => ({
    notifications: [],

    add: (notification) => {
      const id = crypto.randomUUID();
      const duration = notification.duration ?? DEFAULT_DURATION;

      set((state) => {
        state.notifications.push({
          ...notification,
          id,
          dismissible: notification.dismissible ?? true,
        });
      });

      // Auto-dismiss after duration
      if (duration > 0) {
        setTimeout(() => {
          get().remove(id);
        }, duration);
      }

      return id;
    },

    remove: (id) =>
      set((state) => {
        state.notifications = state.notifications.filter((n) => n.id !== id);
      }),

    clear: () => set({ notifications: [] }),
  }))
);

// ✅ Convenience functions
export const toast = {
  info: (title: string, message?: string) =>
    useNotificationStore.getState().add({ type: 'info', title, message }),

  success: (title: string, message?: string) =>
    useNotificationStore.getState().add({ type: 'success', title, message }),

  warning: (title: string, message?: string) =>
    useNotificationStore.getState().add({ type: 'warning', title, message }),

  error: (title: string, message?: string) =>
    useNotificationStore.getState().add({ type: 'error', title, message, duration: 0 }),
};

// ✅ Selectors
export const useNotifications = () => useNotificationStore((s) => s.notifications);
export const useHasNotifications = () => useNotificationStore((s) => s.notifications.length > 0);

Zustand Anti-Patterns & React Query Integration

Anti-Patterns (FORBIDDEN)

// FORBIDDEN: Destructuring entire store
const { count, increment } = useStore(); // Re-renders on ANY state change

// FORBIDDEN: Storing derived/computed state
const useStore = create((set) => ({
  items: [],
  total: 0, // Will get out of sync!
}));

// FORBIDDEN: Storing server state
const useStore = create((set) => ({
  users: [], // Use TanStack Query instead
  fetchUsers: async () => { ... },
}));

// FORBIDDEN: Mutating state without Immer
set((state) => {
  state.items.push(item); // Breaks reactivity!
  return state;
});

// FORBIDDEN: Using deprecated shallow import
import { shallow } from 'zustand/shallow'; // Use useShallow from zustand/react/shallow

Integration with React Query

// Zustand for CLIENT state (UI, preferences, local-only)
const useUIStore = create<UIState>()((set) => ({
  sidebarOpen: false,
  theme: 'light',
  toggleSidebar: () => set((s) => ({ sidebarOpen: !s.sidebarOpen })),
}));

// TanStack Query for SERVER state (API data)
function Dashboard() {
  const sidebarOpen = useUIStore((s) => s.sidebarOpen);
  const { data: users } = useQuery({ queryKey: ['users'], queryFn: fetchUsers });
  // Zustand: UI state | TanStack Query: server data
}

Zustand Core Patterns

1. Basic Store with TypeScript

import { create } from 'zustand';

interface BearState {
  bears: number;
  increase: (by: number) => void;
  reset: () => void;
}

const useBearStore = create<BearState>()((set) => ({
  bears: 0,
  increase: (by) => set((state) => ({ bears: state.bears + by })),
  reset: () => set({ bears: 0 }),
}));

2. Slices Pattern (Modular Stores)

import { create, StateCreator } from 'zustand';

// Auth slice
interface AuthSlice {
  user: User | null;
  login: (user: User) => void;
  logout: () => void;
}

const createAuthSlice: StateCreator<AuthSlice & CartSlice, [], [], AuthSlice> = (set) => ({
  user: null,
  login: (user) => set({ user }),
  logout: () => set({ user: null }),
});

// Cart slice
interface CartSlice {
  items: CartItem[];
  addItem: (item: CartItem) => void;
  clearCart: () => void;
}

const createCartSlice: StateCreator<AuthSlice & CartSlice, [], [], CartSlice> = (set) => ({
  items: [],
  addItem: (item) => set((state) => ({ items: [...state.items, item] })),
  clearCart: () => set({ items: [] }),
});

// Combined store
const useStore = create<AuthSlice & CartSlice>()((...a) => ({
  ...createAuthSlice(...a),
  ...createCartSlice(...a),
}));

3. Immer Middleware (Immutable Updates)

import { create } from 'zustand';
import { immer } from 'zustand/middleware/immer';

interface TodoState {
  todos: Todo[];
  addTodo: (text: string) => void;
  toggleTodo: (id: string) => void;
  updateNested: (id: string, subtaskId: string, done: boolean) => void;
}

const useTodoStore = create<TodoState>()(
  immer((set) => ({
    todos: [],
    addTodo: (text) =>
      set((state) => {
        state.todos.push({ id: crypto.randomUUID(), text, done: false });
      }),
    toggleTodo: (id) =>
      set((state) => {
        const todo = state.todos.find((t) => t.id === id);
        if (todo) todo.done = !todo.done;
      }),
    updateNested: (id, subtaskId, done) =>
      set((state) => {
        const todo = state.todos.find((t) => t.id === id);
        const subtask = todo?.subtasks?.find((s) => s.id === subtaskId);
        if (subtask) subtask.done = done;
      }),
  }))
);

4. Persist Middleware

import { create } from 'zustand';
import { persist, createJSONStorage } from 'zustand/middleware';

interface SettingsState {
  theme: 'light' | 'dark';
  language: string;
  setTheme: (theme: 'light' | 'dark') => void;
}

const useSettingsStore = create<SettingsState>()(
  persist(
    (set) => ({
      theme: 'light',
      language: 'en',
      setTheme: (theme) => set({ theme }),
    }),
    {
      name: 'settings-storage',
      storage: createJSONStorage(() => localStorage),
      partialize: (state) => ({ theme: state.theme }), // Only persist theme
      version: 1,
      migrate: (persisted, version) => {
        if (version === 0) {
          // Migration logic
        }
        return persisted as SettingsState;
      },
    }
  )
);

5. Selectors (Prevent Re-renders)

// BAD: Re-renders on ANY state change
const { bears, fish } = useBearStore();

// GOOD: Only re-renders when bears changes
const bears = useBearStore((state) => state.bears);

// GOOD: Shallow comparison for objects (Zustand 5.x)
import { useShallow } from 'zustand/react/shallow';

const { bears, fish } = useBearStore(
  useShallow((state) => ({ bears: state.bears, fish: state.fish }))
);

// GOOD: Computed/derived state via selector
const totalAnimals = useBearStore((state) => state.bears + state.fish);

// BAD: Storing computed state
const useStore = create((set) => ({
  items: [],
  total: 0, // Don't store derived values!
  addItem: (item) => set((s) => ({
    items: [...s.items, item],
    total: s.total + item.price, // Sync issues!
  })),
}));

// GOOD: Compute in selector
const total = useStore((s) => s.items.reduce((sum, i) => sum + i.price, 0));

6. Async Actions

interface UserState {
  user: User | null;
  loading: boolean;
  error: string | null;
  fetchUser: (id: string) => Promise<void>;
}

const useUserStore = create<UserState>()((set) => ({
  user: null,
  loading: false,
  error: null,
  fetchUser: async (id) => {
    set({ loading: true, error: null });
    try {
      const user = await api.getUser(id);
      set({ user, loading: false });
    } catch (error) {
      set({ error: error.message, loading: false });
    }
  },
}));

7. DevTools Integration

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

const useStore = create<State>()(
  devtools(
    (set) => ({
      // ... state and actions
    }),
    { name: 'MyStore', enabled: process.env.NODE_ENV === 'development' }
  )
);

Middleware Composition

Comprehensive guide to combining Zustand middleware in the correct order for production applications.

Middleware Execution Order

Middleware wraps from inside out. The innermost middleware executes first, outermost last.

┌─────────────────────────────────────────────────────────────┐
│ persist (outermost - serializes final state)                │
│  ┌───────────────────────────────────────────────────────┐  │
│  │ devtools (records actions after transformation)       │  │
│  │  ┌─────────────────────────────────────────────────┐  │  │
│  │  │ subscribeWithSelector (enables granular subs)   │  │  │
│  │  │  ┌───────────────────────────────────────────┐  │  │  │
│  │  │  │ immer (innermost - transforms mutations)  │  │  │  │
│  │  │  │                                           │  │  │  │
│  │  │  │   Your store logic lives here             │  │  │  │
│  │  │  │                                           │  │  │  │
│  │  │  └───────────────────────────────────────────┘  │  │  │
│  │  └─────────────────────────────────────────────────┘  │  │
│  └───────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘

Why Order Matters

Complete Production Setup

import { create } from 'zustand';
import { devtools, persist, subscribeWithSelector, createJSONStorage } from 'zustand/middleware';
import { immer } from 'zustand/middleware/immer';
import type {} from '@redux-devtools/extension'; // Required for devtools typing

interface AppState {
  // UI State
  sidebarOpen: boolean;
  theme: 'light' | 'dark' | 'system';

  // User preferences
  notifications: {
    email: boolean;
    push: boolean;
    sms: boolean;
  };

  // Actions
  toggleSidebar: () => void;
  setTheme: (theme: 'light' | 'dark' | 'system') => void;
  updateNotification: (key: keyof AppState['notifications'], value: boolean) => void;
  reset: () => void;
}

const initialState = {
  sidebarOpen: true,
  theme: 'system' as const,
  notifications: {
    email: true,
    push: true,
    sms: false,
  },
};

export const useAppStore = create<AppState>()(
  persist(
    devtools(
      subscribeWithSelector(
        immer((set, get) => ({
          ...initialState,

          toggleSidebar: () =>
            set(
              (state) => { state.sidebarOpen = !state.sidebarOpen; },
              undefined,
              'ui/toggleSidebar' // Action name for devtools
            ),

          setTheme: (theme) =>
            set(
              (state) => { state.theme = theme; },
              undefined,
              'ui/setTheme'
            ),

          updateNotification: (key, value) =>
            set(
              (state) => { state.notifications[key] = value; },
              undefined,
              `notifications/update/${key}`
            ),

          reset: () =>
            set(
              () => initialState,
              true, // Replace entire state
              'app/reset'
            ),
        }))
      ),
      {
        name: 'AppStore',
        enabled: process.env.NODE_ENV === 'development',
        // Sanitize sensitive data from devtools
        serialize: {
          replacer: (key, value) => {
            if (key === 'password' || key === 'token') return '[REDACTED]';
            return value;
          },
        },
      }
    ),
    {
      name: 'app-storage',
      storage: createJSONStorage(() => localStorage),
      version: 2,

      // Only persist specific fields
      partialize: (state) => ({
        theme: state.theme,
        notifications: state.notifications,
        // Don't persist: sidebarOpen (session-only UI state)
      }),

      // Handle migrations between versions
      migrate: (persistedState: unknown, version: number) => {
        const state = persistedState as Partial<AppState>;

        if (version === 0) {
          // v0 → v1: Added notifications
          return {
            ...state,
            notifications: { email: true, push: true, sms: false },
          };
        }

        if (version === 1) {
          // v1 → v2: Changed theme from boolean to union
          return {
            ...state,
            theme: (state as any).darkMode ? 'dark' : 'light',
          };
        }

        return state as AppState;
      },

      // Called when hydration completes
      onRehydrateStorage: () => (state, error) => {
        if (error) {
          console.error('Failed to rehydrate store:', error);
        } else {
          console.log('Store rehydrated:', state?.theme);
        }
      },
    }
  )
);

subscribeWithSelector Usage

Enables subscribing to specific state slices outside React:

// Subscribe to theme changes only
const unsubscribe = useAppStore.subscribe(
  (state) => state.theme,
  (theme, prevTheme) => {
    console.log('Theme changed:', prevTheme, '→', theme);
    document.documentElement.dataset.theme = theme;
  },
  { fireImmediately: true }
);

// Subscribe with equality function
useAppStore.subscribe(
  (state) => state.notifications,
  (notifications) => {
    syncNotificationsToServer(notifications);
  },
  { equalityFn: shallow } // Only trigger if shallow-different
);

// Cleanup
unsubscribe();

Devtools Best Practices

Action Naming Convention

// ✅ GOOD: Namespace/action format
set(state => { ... }, undefined, 'cart/addItem');
set(state => { ... }, undefined, 'auth/login');
set(state => { ... }, undefined, 'ui/toggleSidebar');

// ❌ BAD: No action name (shows as "anonymous")
set(state => { ... });

Conditional DevTools

const useStore = create<State>()(
  devtools(
    (set) => ({ ... }),
    {
      name: 'MyStore',
      enabled: process.env.NODE_ENV === 'development',
      // Trace calls for debugging (performance cost!)
      trace: process.env.NODE_ENV === 'development',
      traceLimit: 25,
    }
  )
);

Persist Strategies

Session Storage (Tab-Scoped)

persist(
  (set) => ({ ... }),
  {
    name: 'session-store',
    storage: createJSONStorage(() => sessionStorage),
  }
)

IndexedDB (Large Data)

import { get, set, del } from 'idb-keyval';

const indexedDBStorage = {
  getItem: async (name: string) => {
    return (await get(name)) ?? null;
  },
  setItem: async (name: string, value: string) => {
    await set(name, value);
  },
  removeItem: async (name: string) => {
    await del(name);
  },
};

persist(
  (set) => ({ ... }),
  {
    name: 'large-store',
    storage: createJSONStorage(() => indexedDBStorage),
  }
)

Async Storage (React Native)

import AsyncStorage from '@react-native-async-storage/async-storage';

persist(
  (set) => ({ ... }),
  {
    name: 'mobile-store',
    storage: createJSONStorage(() => AsyncStorage),
  }
)

Middleware Without Full Stack

Immer Only (Simple Apps)

const useStore = create<State>()(
  immer((set) => ({
    items: [],
    addItem: (item) => set((state) => { state.items.push(item); }),
  }))
);

Persist Only (Simple Persistence)

const useStore = create<State>()(
  persist(
    (set) => ({
      theme: 'light',
      setTheme: (theme) => set({ theme }),
    }),
    { name: 'theme-storage' }
  )
);

DevTools Only (Development)

const useStore = create<State>()(
  devtools(
    (set) => ({ ... }),
    { enabled: process.env.NODE_ENV === 'development' }
  )
);

TypeScript Typing for Middleware

When using multiple middleware, TypeScript needs explicit middleware type annotation:

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

interface BearState {
  bears: number;
  increase: () => void;
}

// Explicit middleware types for slices
type BearSlice = StateCreator<
  BearState,
  [['zustand/immer', never], ['zustand/devtools', never]],
  [],
  BearState
>;

const createBearSlice: BearSlice = (set) => ({
  bears: 0,
  increase: () => set((state) => { state.bears += 1; }),
});

const useStore = create<BearState>()(
  devtools(
    immer(createBearSlice),
    { name: 'BearStore' }
  )
);

Common Pitfalls

❌ Wrong Order

// WRONG: persist inside devtools
devtools(persist(immer(...))) // DevTools won't see persist actions

// CORRECT: persist outside devtools
persist(devtools(immer(...)))

❌ Duplicate Middleware

// WRONG: Double-wrapping
persist(persist(...)) // Causes hydration issues

❌ Missing Type Import

// WRONG: DevTools types missing
import { devtools } from 'zustand/middleware';

// CORRECT: Import type augmentation
import { devtools } from 'zustand/middleware';
import type {} from '@redux-devtools/extension';

Rule Categories

1. Middleware (zustand) — CRITICAL — 2 rules

Correct middleware composition order and common pitfalls.

• zustand-middleware-order.md — persist outermost, immer innermost, devtools/subscribeWithSelector in between
• zustand-middleware-pitfalls.md — Avoid direct mutation without immer, async middleware patterns, persist migrations

2. Store Architecture (zustand) — HIGH — 1 rule

Store organization patterns for maintainability.

• zustand-slice-pattern.md — Split large stores into typed slices, combine without circular dependencies

[Rule Name]

[Brief description — 1-2 sentences.]

Incorrect:

// Bad pattern

Correct:

// Good pattern

Key rules:

• [Rule 1]
• [Rule 2]
• [Rule 3]

Reference: [link]

Zustand: Middleware Order

Zustand middleware wraps from inside out. The innermost middleware executes first, and the outermost middleware executes last. Getting this order wrong silently breaks persistence, devtools recording, and immutable updates.

Incorrect:

// WRONG: immer outermost — draft mutations leak to devtools and persist
const useStore = create<AppState>()(
  immer(devtools(persist((set) => ({
    count: 0,
    increment: () => set((state) => { state.count += 1; }),
  }), { name: 'app-storage' }), { name: 'AppStore' }))
);

// WRONG: devtools inside persist — devtools won't see persist rehydration
devtools(persist(immer((set) => ({ /* ... */ })), { name: 'storage' }), { name: 'Store' });

Correct:

import { create } from 'zustand';
import { devtools, persist, subscribeWithSelector } from 'zustand/middleware';
import { immer } from 'zustand/middleware/immer';
import type {} from '@redux-devtools/extension';

// Correct order: persist > devtools > subscribeWithSelector > immer
const useStore = create<AppState>()(
  persist(
    devtools(
      subscribeWithSelector(
        immer((set) => ({
          count: 0,
          increment: () =>
            set(
              (state) => { state.count += 1; },
              undefined,
              'counter/increment'
            ),
        }))
      ),
      { name: 'AppStore', enabled: process.env.NODE_ENV === 'development' }
    ),
    {
      name: 'app-storage',
      partialize: (state) => ({ count: state.count }),
    }
  )
);

Key rules:

• Immer is always innermost -- transforms draft mutations into immutable updates first
• subscribeWithSelector wraps immer -- needs transformed (immutable) state for granular subscriptions
• devtools wraps subscribeWithSelector -- records actions after immer transforms them
• persist is always outermost -- serializes the final, fully transformed state to storage
• When using a subset, preserve relative order (e.g., devtools(immer(...)) not immer(devtools(...)))

Reference: references/middleware-composition.md (Middleware Execution Order, Why Order Matters)

Zustand: Middleware Pitfalls

Four common middleware mistakes that cause silent bugs in Zustand stores.

Pitfall 1: Mutating State Without Immer

Incorrect:

set((state) => { state.items.push(item); return state; }); // Mutates in place, no re-render

Correct:

set((state) => ({ items: [...state.items, item] }));           // Immutable update
immer((set) => ({ addItem: (item) => set((s) => { s.items.push(item); }) })) // With immer

Pitfall 2: Duplicate Middleware / Wrong Nesting

Incorrect:

persist(persist((set) => ({ /* ... */ }), { name: 'a' }), { name: 'b' }) // Double-wrap

Correct:

persist((set) => ({ /* ... */ }), { name: 'app-storage', partialize: (s) => ({ theme: s.theme }) })

Pitfall 3: Missing DevTools Type Import

Incorrect:

import { devtools } from 'zustand/middleware'; // TS errors — types not augmented

Correct:

import { devtools } from 'zustand/middleware';
import type {} from '@redux-devtools/extension'; // Required type augmentation

Pitfall 4: Missing Persist Version Migrations

Incorrect:

persist((set) => ({ theme: 'light', fontSize: 14 }), { name: 'settings', version: 2 })
// Was version 1 — no migrate function, old state silently dropped

Correct:

persist((set) => ({ theme: 'light', fontSize: 14 }), {
  name: 'settings',
  version: 2,
  migrate: (persisted: unknown, version: number) => {
    const state = persisted as Record<string, unknown>;
    if (version === 1) return { ...state, fontSize: 14 }; // v1->v2: added fontSize
    return state;
  },
})

Key rules:

• Never use mutable methods (push, splice, property assignment) in set() without immer middleware
• Never double-wrap the same middleware -- each should appear exactly once
• Always import type {} from '@redux-devtools/extension' when using devtools
• Always provide a migrate function when bumping persist version

Reference: references/middleware-composition.md (Common Pitfalls)

Zustand: Slice Pattern

Split large stores into typed slices using StateCreator. Each slice owns a domain of state and actions, combined into a single store at creation time.

Incorrect:

// Monolithic store — all domains in one create() call
const useStore = create<AllState>()((set, get) => ({
  user: null, token: null,
  login: async (creds) => { /* ... */ },
  logout: () => set({ user: null, token: null }),
  items: [], addItem: (item) => set((s) => ({ items: [...s.items, item] })),
  sidebarOpen: false, theme: 'light',
  toggleSidebar: () => set((s) => ({ sidebarOpen: !s.sidebarOpen })),
  // ... 20 more fields — unmaintainable
}));

Correct:

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

type AppStore = AuthSlice & CartSlice & UISlice;

// --- Auth Slice (store/auth-slice.ts) ---
interface AuthSlice { user: User | null; login: (creds: Credentials) => Promise<void>; logout: () => void; }

const createAuthSlice: StateCreator<
  AppStore, [['zustand/immer', never]], [], AuthSlice
> = (set) => ({
  user: null,
  login: async (creds) => { set({ user: await api.login(creds) }, undefined, 'auth/login'); },
  logout: () => set((s) => { s.user = null; }, undefined, 'auth/logout'),
});

// --- Cart Slice (cross-slice access via get()) ---
interface CartSlice { items: CartItem[]; addItem: (item: CartItem) => void; }

const createCartSlice: StateCreator<
  AppStore, [['zustand/immer', never]], [], CartSlice
> = (set, get) => ({
  items: [],
  addItem: (item) => {
    if (!get().user) return; // Cross-slice access via get()
    set((s) => { s.items.push(item); }, undefined, 'cart/addItem');
  },
});

// --- Combined Store ---
const useStore = create<AppStore>()(
  immer((...a) => ({
    ...createAuthSlice(...a),
    ...createCartSlice(...a),
    ...createUISlice(...a),
  }))
);

Key rules:

• Type each slice as StateCreator<CombinedStore, MiddlewareMutators, [], SliceInterface> for full store type inference
• Combine with spread: create<Store>()((...a) => ({ ...createSliceA(...a), ...createSliceB(...a) })) -- ...a forwards set, get, store
• Access other slices via get() inside actions, never by importing state directly -- avoids circular dependencies
• Keep each slice in its own file, export only the creator function and interface
• Declare middleware mutator types in the StateCreator generic so TypeScript knows available features

Reference: references/middleware-composition.md (TypeScript Typing for Middleware)