Zustand — Modern State Management

A comprehensive guide to zustand — modern state management with production examples and best practices.

Why Zustand? The Problem with Boilerplate State Management

State management in React has long been dominated by Redux, which, while powerful, introduces significant boilerplate: action types, reducers, dispatch, connect, and middleware. For many applications, this overhead is unnecessary. Zustand offers a minimal API that eliminates boilerplate while preserving the benefits of a centralized store. It's a single hook-based store that requires no providers, no context, and no reducers. This section explains the core motivation: when you need global state but don't want to write 50 lines of code to increment a counter. Zustand is not a replacement for Redux in every scenario, but for most CRUD apps, dashboards, and even complex state interactions, it's the right tool. We'll also touch on its performance characteristics: Zustand uses subscriptions to avoid unnecessary re-renders, and it's framework-agnostic, meaning you can use it with vanilla JS or other frameworks.

npm install zustand

Creating Your First Store: The Minimal API

Zustand stores are created with the create function, which takes a callback that returns the initial state and actions. The callback receives set and get functions to update and read state. This section walks through a simple counter store, then a more realistic user preferences store. The API is intentionally minimal: no action types, no reducers, no dispatch. You just call set with a partial state or a function that returns a partial state. This pattern is intuitive and scales well. We'll also show how to access the store outside React (e.g., in a service or utility) using useStore.getState() and useStore.setState(). This is a common need in production for logging, analytics, or imperative updates.

import { create } from 'zustand'

const useStore = create((set) => ({
  count: 0,
  increment: () => set((state) => ({ count: state.count + 1 })),
  decrement: () => set((state) => ({ count: state.count - 1 })),
  reset: () => set({ count: 0 }),
}))

export default useStore

Selectors: Avoiding Unnecessary Re-renders

By default, Zustand re-renders a component whenever any part of the store changes. To optimize, use selectors. A selector is a function that extracts a slice of state. Zustand's useStore hook accepts an optional selector function and an optional equality function. This section explains how to use selectors to prevent re-renders when unrelated state changes. We'll also cover the shallow utility for comparing objects. In production, failing to use selectors can cause performance issues in large stores. We'll show a real example: a store with user data and UI state, where the user profile component should only re-render when user data changes, not when a modal toggles.

import { create } from 'zustand'
import { shallow } from 'zustand/shallow'

const useStore = create((set) => ({
  user: { name: 'Alice', email: 'alice@example.com' },
  ui: { modalOpen: false },
  setUser: (user) => set({ user }),
  toggleModal: () => set((state) => ({ ui: { ...state.ui, modalOpen: !state.ui.modalOpen } })),
}))

// In component:
const user = useStore((state) => state.user, shallow)
// Only re-renders when user object changes

Actions and Async Logic: Keeping It Simple

Zustand actions are just functions that call set. For async logic, you can define async actions directly in the store. No middleware needed. This section shows how to fetch data from an API and update the store. We'll also discuss error handling and loading states. The pattern is straightforward: set loading to true, await the fetch, then set data and loading to false. We'll also cover how to call actions from outside React (e.g., in a service) using useStore.getState().fetchData(). This is useful for background sync or WebSocket handlers. We'll warn against common pitfalls like race conditions and stale closures, and show how to use get to access current state inside async actions.

import { create } from 'zustand'

const useStore = create((set, get) => ({
  data: null,
  loading: false,
  error: null,
  fetchData: async (id) => {
    set({ loading: true, error: null })
    try {
      const response = await fetch(`/api/items/${id}`)
      if (!response.ok) throw new Error('Failed to fetch')
      const data = await response.json()
      set({ data, loading: false })
    } catch (error) {
      set({ error: error.message, loading: false })
    }
  },
}))

export default useStore

Middleware: Persistence, Immer, and Devtools

Zustand supports middleware to extend functionality. The most common are persist (localStorage/sessionStorage), immer (immutable updates with mutable syntax), and devtools (Redux DevTools integration). This section explains how to apply middleware using create with a middleware wrapper. We'll show a production example: persisting user preferences to localStorage, using Immer for complex nested state updates, and connecting to Redux DevTools for debugging. We'll also discuss the order of middleware (e.g., persist should be outermost). We'll warn about the pitfalls of persisting sensitive data and the need to handle versioning when the store shape changes.

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

const useStore = create(
  persist(
    immer((set) => ({
      user: { name: '', preferences: { theme: 'light', fontSize: 14 } },
      updateTheme: (theme) =>
        set((state) => {
          state.user.preferences.theme = theme
        }),
    })),
    {
      name: 'user-preferences',
      version: 1,
    }
  )
)

export default useStore

Testing Zustand Stores: Unit Tests That Matter

Testing state management is critical. Zustand stores are plain functions, making them easy to test without React. This section shows how to write unit tests for store actions and selectors using Jest or Vitest. We'll test async actions by mocking fetch, and verify state transitions. We'll also test selectors for correct memoization. We'll discuss the importance of testing error states and edge cases. In production, untested stores lead to regressions when refactoring. We'll provide a complete test example with mocking and assertions.

import { create } from 'zustand'

const useStore = create((set) => ({
  count: 0,
  increment: () => set((state) => ({ count: state.count + 1 })),
}))

describe('counter store', () => {
  beforeEach(() => {
    useStore.setState({ count: 0 })
  })

  it('increments count', () => {
    const { increment } = useStore.getState()
    increment()
    expect(useStore.getState().count).toBe(1)
  })

  it('resets count', () => {
    useStore.setState({ count: 5 })
    useStore.getState().reset()
    expect(useStore.getState().count).toBe(0)
  })
})

Scaling Zustand: Slicing Stores and Combining

As your app grows, a single store becomes unwieldy. Zustand encourages splitting stores by domain. This section shows how to create multiple stores and combine them in components. We'll also discuss cross-store communication: one store can subscribe to another using subscribe or by calling actions from another store. We'll cover the pattern of a root store that composes slices, but warn against over-engineering. In production, we've seen teams create 50+ stores without issues, as long as each store is focused. We'll also show how to use useStore with multiple stores in a single component.

import { create } from 'zustand'

export const useUserStore = create((set) => ({
  user: null,
  setUser: (user) => set({ user }),
}))

export const useCartStore = create((set) => ({
  items: [],
  addItem: (item) => set((state) => ({ items: [...state.items, item] })),
}))

// In component:
const user = useUserStore((state) => state.user)
const items = useCartStore((state) => state.items)

Performance Pitfalls and How to Avoid Them

Even with selectors, Zustand can cause performance issues if misused. This section covers common pitfalls: creating new objects in selectors, subscribing to large slices, and using inline functions that break memoization. We'll show how to use useShallow from zustand/shallow for deep equality, and how to use subscribe for side effects without re-renders. We'll also discuss the cost of set with large state trees and recommend using Immer for efficient updates. In production, we've seen apps where a single store update caused 100+ components to re-render due to missing selectors. We'll provide a checklist for performance optimization.

import { useShallow } from 'zustand/shallow'

// Bad: creates new object every render
const { user, theme } = useStore((state) => ({
  user: state.user,
  theme: state.theme,
}))

// Good: use shallow equality
const { user, theme } = useStore(
  useShallow((state) => ({
    user: state.user,
    theme: state.theme,
  }))
)

Zustand with TypeScript: Type Safety Without Pain

Zustand has excellent TypeScript support. This section shows how to type the store, actions, and selectors. We'll define an interface for the state and actions, and use create with the type parameter. We'll also show how to type middleware like persist and immer. We'll discuss the StateCreator type for reusable store patterns. In production, TypeScript catches bugs like misspelled action names or wrong payload types. We'll provide a complete typed store example and show how to use useStore with selectors that infer types.

import { create } from 'zustand'

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

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

// In component:
const bears = useBearStore((state) => state.bears)
const increase = useBearStore((state) => state.increase)

Real-World Patterns: Authentication and Caching

This section applies Zustand to common production scenarios: authentication state and API caching. For auth, we'll create a store that holds user, token, and login/logout actions, with persistence to localStorage. For caching, we'll implement a simple cache store that stores API responses with timestamps and TTL. We'll discuss how to handle token refresh and cache invalidation. These patterns are battle-tested in production. We'll also show how to use Zustand's subscribe to sync auth state with other parts of the app (e.g., redirect on logout).

import { create } from 'zustand'
import { persist } from 'zustand/middleware'

const useAuthStore = create(
  persist(
    (set) => ({
      user: null,
      token: null,
      login: async (email, password) => {
        const res = await fetch('/api/login', { method: 'POST', body: { email, password } })
        const data = await res.json()
        set({ user: data.user, token: data.token })
      },
      logout: () => set({ user: null, token: null }),
    }),
    { name: 'auth' }
  )
)

export default useAuthStore

Migrating from Redux to Zustand: A Step-by-Step Guide

If you're considering migrating from Redux, this section provides a practical roadmap. We'll show how to map Redux concepts to Zustand: reducers become actions, selectors remain similar, and middleware like thunks become async actions. We'll demonstrate a migration of a simple todo app. We'll discuss strategies: incremental migration (one slice at a time) vs big bang. We'll also cover how to handle side effects (e.g., sagas) — in Zustand, you can use subscribe or call actions from within other actions. We'll warn about common migration pitfalls like forgetting to remove Provider wrappers or mis-handling middleware.

// Redux reducer
const todoReducer = (state = [], action) => {
  switch (action.type) {
    case 'ADD_TODO':
      return [...state, action.payload]
    default:
      return state
  }
}

// Zustand equivalent
const useTodoStore = create((set) => ({
  todos: [],
  addTodo: (todo) => set((state) => ({ todos: [...state.todos, todo] })),
}))

When Not to Use Zustand: Alternatives and Trade-offs

Zustand is not a silver bullet. This section discusses scenarios where other tools might be better: for server state, use TanStack Query; for complex forms, use Formik or React Hook Form; for highly concurrent state with undo/redo, consider XState. We'll also compare Zustand with Jotai and Recoil (atomic state) and Context API (for low-frequency updates). We'll give honest trade-offs: Zustand lacks built-in support for computed properties (use selectors or external libraries), and its middleware ecosystem is smaller than Redux's. In production, choosing the right tool is critical. We'll provide a decision tree.

// Decision tree:
// - Server state? -> TanStack Query
// - Form state? -> React Hook Form
// - Complex workflows? -> XState
// - Simple global state? -> Zustand
// - Atomic state? -> Jotai

Zustand with TypeScript: Full Type Safety

TypeScript integration in Zustand is seamless and provides full type safety without extra boilerplate. Define your store's state and actions as a type or interface, then pass it to create. For example:

```typescript import { create } from 'zustand';

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

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

This ensures that useBearStore returns correctly typed state and actions. For slices, use StateCreator to type each slice. Middleware like persist also supports generics for the storage type. TypeScript catches errors at compile time, reducing runtime bugs. Use unknown for external data and validate with Zod if needed.

import { create } from 'zustand';

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

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

Zustand Persist Middleware: localStorage and Cookies

The persist middleware in Zustand allows you to save and rehydrate store state to storage like localStorage, sessionStorage, or cookies. To use it, wrap your store creation with persist and specify a name (key) and optional storage (default is localStorage). Example:

```typescript import { create } from 'zustand'; import { persist } from 'zustand/middleware';

interface AuthStore { token: string | null; setToken: (token: string) => void; logout: () => void; }

const useAuthStore = create<AuthStore>()( persist( (set) => ({ token: null, setToken: (token) => set({ token }), logout: () => set({ token: null }), }), { name: 'auth-storage', storage: { getItem: (name) => { const value = localStorage.getItem(name); return value ? JSON.parse(value) : null; }, setItem: (name, value) => { localStorage.setItem(name, JSON.stringify(value)); }, removeItem: (name) => localStorage.removeItem(name), }, } ) ); ```

For cookies, use a custom storage that reads/writes cookies. You can also use partialize to persist only specific fields. The middleware automatically rehydrates on app load. For SSR, ensure storage is only accessed on the client side.

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

interface AuthStore {
  token: string | null;
  setToken: (token: string) => void;
  logout: () => void;
}

const useAuthStore = create<AuthStore>()(
  persist(
    (set) => ({
      token: null,
      setToken: (token) => set({ token }),
      logout: () => set({ token: null }),
    }),
    {
      name: 'auth-storage',
      storage: {
        getItem: (name) => {
          const value = localStorage.getItem(name);
          return value ? JSON.parse(value) : null;
        },
        setItem: (name, value) => {
          localStorage.setItem(name, JSON.stringify(value));
        },
        removeItem: (name) => localStorage.removeItem(name),
      },
    }
  )
);

Zustand vs Jotai vs Context: Choosing the Right Tool

Zustand, Jotai, and React Context each solve state management differently. Zustand is a minimal, external store with a single store (or multiple slices) and subscriptions. It's great for global state, cross-component communication, and when you need middleware like persistence. Jotai is atomic: each piece of state is an atom, and components subscribe to atoms directly. It's ideal for fine-grained reactivity and avoids unnecessary re-renders without selectors. React Context is built-in but causes re-renders for all consumers when any part of the context value changes. It's best for low-frequency updates like themes or authentication status.

Choose Zustand for global state with complex logic, Jotai for fine-grained reactivity, and Context for simple, low-frequency state.

// Zustand
const useStore = create((set) => ({ count: 0, increment: () => set((s) => ({ count: s.count + 1 })) }));

// Jotai
import { atom, useAtom } from 'jotai';
const countAtom = atom(0);
const [count, setCount] = useAtom(countAtom);

// Context
const CountContext = createContext({ count: 0, increment: () => {} });