Zustand State Management

Common errors

• TypeError: Cannot destructure property 'create' of 'zustand' as it is undefined.

  cause Attempting to use CommonJS `require` syntax for `zustand` which might primarily target ESM, or an incorrect module import path.
  fix Ensure you are using `import { create } from 'zustand'` and your build system is configured for ESM.

• Error: Invalid hook call. Hooks can only be called inside of the body of a function component.

  cause Calling `useBearStore` or any other Zustand store hook outside of a React function component or another custom React Hook.
  fix Ensure all Zustand store hooks are invoked exclusively within the top level of React function components or custom hooks.

• TypeError: Cannot read properties of undefined (reading 'propertyName')

  cause A `set` callback returned `void` or `undefined` instead of a state object, causing the store state to become invalid or partial updates to fail.
  fix Always ensure `set` callbacks return a complete (or new partial) state object. For example, `set((state) => ({ ...state, propertyName: newValue }))`.

Warnings

• gotcha State updates must be immutable. Directly modifying state objects will not trigger re-renders or correctly persist changes.
  Fix: Always return a new state object from `set` callbacks (e.g., `set((state) => ({ ...state, property: newValue }))`) or provide a new object when calling `set`.
• gotcha Selecting the entire store state (e.g., `useBearStore()`) will cause your component to re-render on *any* state change within the store, which can lead to performance issues.
  Fix: Select only the specific state slices your component needs (e.g., `useBearStore((state) => state.bears)`). For multiple non-primitive slices, consider `shallow` from `zustand/shallow` or a custom equality function.
• gotcha Selectors use strict-equality (`old === new`) for comparison by default. If your selector returns a new object or array on every render, it will cause unnecessary re-renders even if the underlying data is shallowly identical.
  Fix: For non-primitive return values from selectors (e.g., `useBearStore((state) => ({ count: state.bears, name: state.name }))`), use `shallow` from `zustand/shallow` as a second argument to `useBearStore` (e.g., `useBearStore(selector, shallow)`).
• gotcha When using the `persist` middleware, directly manipulating the underlying storage (like `localStorage`) outside of Zustand's API can lead to state inconsistencies or race conditions, especially during concurrent rehydration.
  Fix: Manage all persistent state exclusively through Zustand's `persist` middleware and `set` function, avoiding direct interaction with the storage API.

Install

• npm install zustand npm
• yarn add zustand yarn
• pnpm add zustand pnpm

Imports

• create
  wrong:

  const { create } = require('zustand')

  correct:

  import { create } from 'zustand'

  Zustand is primarily designed for ESM usage with React hooks. While CommonJS might work with some bundlers, ESM is the recommended and idiomatic approach.

Quickstart

This quickstart defines a simple Zustand store, `useBearStore`, with initial state and actions. It then demonstrates how to consume and update this state from two separate React components without needing a Provider.

import { create } from 'zustand';

const useBearStore = create((set) => ({
  bears: 0,
  increasePopulation: () => set((state) => ({ bears: state.bears + 1 })),
  removeAllBears: () => set({ bears: 0 }),
}));

function BearCounter() {
  const bears = useBearStore((state) => state.bears);
  return <h1>{bears} around here ...</h1>;
}

function Controls() {
  const increasePopulation = useBearStore((state) => state.increasePopulation);
  return <button onClick={increasePopulation}>one up</button>;
}