zustand-patterns

name	zustand-patterns
description	Zustand store management with slices, middleware, selectors, and TypeScript patterns

Zustand Patterns — Global State Management

Overview

Zustand patterns for client state:

• Curried syntax with TypeScript
• Store slices organization
• Middleware (devtools, persist, immer)
• Granular selectors
• Feature-scoped vs global stores
• When to use Zustand vs TanStack Query vs Context

---

Hard Rules

These rules are NON-NEGOTIABLE. Violating any of them is a bug.

• ALWAYS use curried syntax in TypeScript: create<State>()((...) => ({...}))
• NEVER destructure entire store — ALWAYS use granular selectors
• ALWAYS use useShallow when selecting multiple values
• ALWAYS define state + actions in one interface
• NEVER mutate state directly unless using immer middleware
• ALWAYS use devtools middleware in development
• ALWAYS use partialize with persist — NEVER persist entire store
• NEVER store server/API data in Zustand — use TanStack Query for server state
• ALWAYS reset stores between tests via useStore.setState(useStore.getInitialState())
• NEVER use Zustand for form state — use React Hook Form

---

State Management Decision Matrix

Concern	Tool	Why
Server/API data	TanStack Query	Caching, deduplication, background refresh
Global client state	Zustand	Lightweight, no boilerplate, fast
Local component state	useState / useReducer	Simplest option, no external deps
Rarely-changing tree-wide values	React Context	Theme, locale, auth user
Form state	React Hook Form	Validation, field management, performance
URL-driven state	Router search params	Shareable, bookmarkable, SSR-friendly

Rule: If the data comes from an API, it goes in TanStack Query. If it's client-only UI state, use Zustand. If it's scoped to one component, use useState.

---

Store Setup — Curried Syntax

Why Curried Syntax?

TypeScript cannot infer generics on create<State>() without currying. The extra () enables full type inference.

// ❌ BAD: Without currying — types not inferred correctly
const useStore = create<State>((set) => ({...}));

// ✅ GOOD: Curried syntax — full type inference
const useStore = create<State>()((...) => ({...}));

Basic Store

// src/stores/ui-store.ts
import { create } from 'zustand';

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

  // Actions
  toggleSidebar: () => void;
  setSidebarOpen: (open: boolean) => void;
  setTheme: (theme: UIState['theme']) => void;
}

export const useUIStore = create<UIState>()((set) => ({
  // Initial state
  sidebarOpen: true,
  theme: 'system',

  // Actions
  toggleSidebar: () => set((state) => ({ sidebarOpen: !state.sidebarOpen })),
  setSidebarOpen: (open) => set({ sidebarOpen: open }),
  setTheme: (theme) => set({ theme }),
}));

---

Granular Selectors

Single Value Selector

// ✅ GOOD: Select only what you need — component re-renders only when sidebarOpen changes
function Sidebar(): React.ReactElement {
  const sidebarOpen = useUIStore((state) => state.sidebarOpen);
  return sidebarOpen ? <nav>Sidebar content</nav> : null;
}

Multiple Values with useShallow

import { useShallow } from 'zustand/react/shallow';

// ✅ GOOD: useShallow prevents re-renders when unrelated state changes
function Header(): React.ReactElement {
  const { sidebarOpen, theme, toggleSidebar } = useUIStore(
    useShallow((state) => ({
      sidebarOpen: state.sidebarOpen,
      theme: state.theme,
      toggleSidebar: state.toggleSidebar,
    }))
  );

  return (
    <header>
      <button onClick={toggleSidebar}>
        {sidebarOpen ? 'Close' : 'Open'}
      </button>
      <span>Theme: {theme}</span>
    </header>
  );
}

// ❌ BAD: Destructuring entire store — re-renders on ANY state change
function Header(): React.ReactElement {
  const { sidebarOpen, theme, toggleSidebar } = useUIStore();
  // This re-renders when ANY store value changes, not just these three
}

Reusable Selector Hooks

// src/stores/selectors.ts
import { useUIStore } from './ui-store';

export function useSidebarOpen(): boolean {
  return useUIStore((state) => state.sidebarOpen);
}

export function useTheme(): UIState['theme'] {
  return useUIStore((state) => state.theme);
}

// Usage in components:
function Sidebar(): React.ReactElement {
  const sidebarOpen = useSidebarOpen();
  // ...
}

---

Slices Pattern

For stores with multiple domains, split into slices that combine into one store.

Auth Slice

// src/stores/slices/auth-slice.ts
import type { StateCreator } from 'zustand';

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

export interface AuthSlice {
  // State
  user: User | null;
  isAuthenticated: boolean;

  // Actions
  setUser: (user: User) => void;
  logout: () => void;
}

export const createAuthSlice: StateCreator<
  AuthSlice & UISlice, // Full store type for cross-slice access
  [],
  [],
  AuthSlice
> = (set) => ({
  user: null,
  isAuthenticated: false,

  setUser: (user) => set({ user, isAuthenticated: true }),
  logout: () => set({ user: null, isAuthenticated: false }),
});

UI Slice

// src/stores/slices/ui-slice.ts
import type { StateCreator } from 'zustand';

export interface UISlice {
  sidebarOpen: boolean;
  theme: 'light' | 'dark' | 'system';
  toggleSidebar: () => void;
  setTheme: (theme: UISlice['theme']) => void;
}

export const createUISlice: StateCreator<
  AuthSlice & UISlice,
  [],
  [],
  UISlice
> = (set) => ({
  sidebarOpen: true,
  theme: 'system',
  toggleSidebar: () => set((state) => ({ sidebarOpen: !state.sidebarOpen })),
  setTheme: (theme) => set({ theme }),
});

Combining Slices

// src/stores/app-store.ts
import { create } from 'zustand';
import { devtools, persist } from 'zustand/middleware';
import { immer } from 'zustand/middleware/immer';

import type { AuthSlice } from './slices/auth-slice';
import { createAuthSlice } from './slices/auth-slice';
import type { UISlice } from './slices/ui-slice';
import { createUISlice } from './slices/ui-slice';

type AppStore = AuthSlice & UISlice;

export const useAppStore = create<AppStore>()(
  devtools(
    persist(
      immer((...args) => ({
        ...createAuthSlice(...args),
        ...createUISlice(...args),
      })),
      {
        name: 'app-store',
        partialize: (state) => ({
          // Only persist these values — never entire store
          theme: state.theme,
          sidebarOpen: state.sidebarOpen,
        }),
      }
    ),
    { name: 'AppStore' }
  )
);

---

Middleware

Middleware Ordering

The correct nesting order (outermost to innermost):

devtools( persist( immer( storeCreator ) ) )

Why this order:

1. devtools wraps everything — sees final state changes
2. persist persists after immer processes
3. immer enables direct mutations in the innermost layer

devtools — Development Debugging

import { devtools } from 'zustand/middleware';

const useStore = create<State>()(
  devtools(
    (set) => ({
      count: 0,
      increment: () => set(
        (state) => ({ count: state.count + 1 }),
        undefined,
        'increment' // Action name in Redux DevTools
      ),
    }),
    { name: 'CounterStore' }
  )
);

persist — LocalStorage

import { persist } from 'zustand/middleware';

const useStore = create<State>()(
  persist(
    (set) => ({
      theme: 'system',
      sidebarOpen: true,
      user: null,         // Should NOT be persisted
      setTheme: (theme) => set({ theme }),
    }),
    {
      name: 'ui-preferences',
      // ✅ GOOD: Only persist what's needed
      partialize: (state) => ({
        theme: state.theme,
        sidebarOpen: state.sidebarOpen,
      }),
      // Optional: custom storage
      // storage: createJSONStorage(() => sessionStorage),
    }
  )
);

immer — Direct Mutations

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

interface TodoState {
  todos: Array<{ id: string; text: string; done: boolean }>;
  addTodo: (text: string) => void;
  toggleTodo: (id: string) => void;
  removeTodo: (id: string) => void;
}

const useTodoStore = create<TodoState>()(
  immer((set) => ({
    todos: [],
    addTodo: (text) =>
      set((state) => {
        // Direct mutation — immer handles immutability
        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;
        }
      }),
    removeTodo: (id) =>
      set((state) => {
        const index = state.todos.findIndex((t) => t.id === id);
        if (index !== -1) {
          state.todos.splice(index, 1);
        }
      }),
  }))
);

---

Feature-Scoped Stores

For non-global state that belongs to a specific feature:

// src/features/kanban/stores/kanban-store.ts
import { create } from 'zustand';

interface KanbanState {
  draggedCardId: string | null;
  activeColumn: string | null;
  setDraggedCard: (id: string | null) => void;
  setActiveColumn: (column: string | null) => void;
}

export const useKanbanStore = create<KanbanState>()((set) => ({
  draggedCardId: null,
  activeColumn: null,
  setDraggedCard: (id) => set({ draggedCardId: id }),
  setActiveColumn: (column) => set({ activeColumn: column }),
}));

Rule: Feature-scoped stores live in src/features/<name>/stores/. They are NOT imported by other features — only by the feature's own components and hooks.

---

Testing Stores

Reset Between Tests

// test/setup.ts or in each test file
import { beforeEach } from 'vitest';
import { useAppStore } from '@/stores/app-store';

beforeEach(() => {
  // Reset to initial state between tests
  useAppStore.setState(useAppStore.getInitialState());
});

Testing Store Logic (Without Rendering)

import { describe, it, expect, beforeEach } from 'vitest';
import { useAppStore } from '@/stores/app-store';

describe('AppStore - Auth Slice', () => {
  beforeEach(() => {
    useAppStore.setState(useAppStore.getInitialState());
  });

  it('sets user on login', () => {
    const user = { id: '1', email: '[e-mail]', name: 'Test' };
    useAppStore.getState().setUser(user);

    expect(useAppStore.getState().user).toEqual(user);
    expect(useAppStore.getState().isAuthenticated).toBe(true);
  });

  it('clears user on logout', () => {
    // Setup: log in first
    useAppStore.getState().setUser({ id: '1', email: '[e-mail]', name: 'Test' });

    // Act
    useAppStore.getState().logout();

    // Assert
    expect(useAppStore.getState().user).toBeNull();
    expect(useAppStore.getState().isAuthenticated).toBe(false);
  });
});

Testing Components That Use Stores

import { describe, it, expect, beforeEach } from 'vitest';
import { render, screen } from '@/test/test-utils';
import userEvent from '@testing-library/user-event';
import { useUIStore } from '@/stores/ui-store';
import { Sidebar } from './Sidebar';

describe('Sidebar', () => {
  beforeEach(() => {
    useUIStore.setState(useUIStore.getInitialState());
  });

  it('shows sidebar when open', () => {
    useUIStore.setState({ sidebarOpen: true });
    render(<Sidebar />);
    expect(screen.getByRole('navigation')).toBeInTheDocument();
  });

  it('hides sidebar when closed', () => {
    useUIStore.setState({ sidebarOpen: false });
    render(<Sidebar />);
    expect(screen.queryByRole('navigation')).not.toBeInTheDocument();
  });

  it('toggles sidebar on button click', async () => {
    const user = userEvent.setup();
    render(<Sidebar />);

    await user.click(screen.getByRole('button', { name: /toggle/i }));
    expect(useUIStore.getState().sidebarOpen).toBe(false);
  });
});

---

Common Mistakes

❌ Server State in Zustand

// WRONG: API data in Zustand
const useStore = create<State>()((set) => ({
  users: [],
  fetchUsers: async () => {
    const users = await api.getUsers();
    set({ users }); // Stale immediately, no cache, no dedup
  },
}));

// CORRECT: Use TanStack Query for server state
const usersQuery = queryOptions({
  queryKey: ['users'],
  queryFn: fetchUsers,
});

❌ Destructuring Entire Store

// WRONG: Re-renders on any state change
const { theme } = useStore();

// CORRECT: Re-renders only when theme changes
const theme = useStore((state) => state.theme);

❌ Persisting Sensitive Data

// WRONG: Persisting auth tokens in localStorage
persist(store, {
  name: 'app',
  // No partialize = everything persisted, including tokens
});

// CORRECT: Only persist safe UI preferences
persist(store, {
  name: 'app',
  partialize: (state) => ({
    theme: state.theme,
    sidebarOpen: state.sidebarOpen,
    // Never persist: user, tokens, session data
  }),
});

---

Summary

1. ✅ Curried syntax for TypeScript inference
2. ✅ Granular selectors, useShallow for multiple values
3. ✅ Slices pattern for organized domain logic
4. ✅ Middleware ordering: devtools(persist(immer(...)))
5. ✅ partialize on persist — never persist entire store
6. ✅ Server state in TanStack Query, client state in Zustand
7. ✅ Reset stores in tests via getInitialState()