Zustand State skill for Codex

Done well means: the store holds client state only (UI, drafts, session preferences), components subscribe to the smallest value they render, actions live next to the state they change, persisted state is versioned, and SSR apps never share one store instance across requests.

Before you start

1. Read AGENTS.md and check zustand in package.json. This skill targets v5 (React 18+, useShallow from zustand/react/shallow, no default export).
2. Find existing stores (grep -rln "from 'zustand'\|from \"zustand\"" src) and follow their file layout and naming.
3. Decide whether the data belongs in Zustand at all:

Data	Home
Server data (lists, records, user profile from API)	TanStack Query, RTK Query or route loaders
URL-shareable state (filters, tab, page)	search params
Form drafts for one form	form library or local state
State used by one component subtree	useState / useReducer / context
Cross-cutting client state (sidebar, cart before checkout, editor selection, wizard progress)	Zustand

Store template

// src/stores/cart-store.ts
import { create } from "zustand";
import { devtools, persist, createJSONStorage } from "zustand/middleware";

type CartItem = { sku: string; qty: number };

type CartState = {
  items: CartItem[];
  couponCode: string | null;
  actions: {
    add: (sku: string) => void;
    setQty: (sku: string, qty: number) => void;
    clear: () => void;
  };
};

export const useCartStore = create<CartState>()(
  devtools(
    persist(
      (set) => ({
        items: [],
        couponCode: null,
        actions: {
          add: (sku) =>
            set((s) => {
              const existing = s.items.find((i) => i.sku === sku);
              return {
                items: existing
                  ? s.items.map((i) => (i.sku === sku ? { ...i, qty: i.qty + 1 } : i))
                  : [...s.items, { sku, qty: 1 }],
              };
            }, undefined, "cart/add"),
          setQty: (sku, qty) =>
            set((s) => ({ items: s.items.map((i) => (i.sku === sku ? { ...i, qty } : i)) }), undefined, "cart/setQty"),
          clear: () => set({ items: [], couponCode: null }, undefined, "cart/clear"),
        },
      }),
      {
        name: "cart-v1",
        version: 1,
        storage: createJSONStorage(() => localStorage),
        partialize: (s) => ({ items: s.items, couponCode: s.couponCode }), // never persist actions
        migrate: (persisted, version) => {
          if (version === 0) {
            // v0 stored { lines: [...] }
            const old = persisted as { lines?: CartItem[] };
            return { items: old.lines ?? [], couponCode: null };
          }
          return persisted as Pick<CartState, "items" | "couponCode">;
        },
      },
    ),
    { name: "cart" },
  ),
);

// Export hooks, not the store, so components cannot subscribe to everything.
export const useCartItems = () => useCartStore((s) => s.items);
export const useCartCount = () => useCartStore((s) => s.items.reduce((n, i) => n + i.qty, 0));
export const useCartActions = () => useCartStore((s) => s.actions);

• Use the curried create<T>()(...) form in TypeScript so middleware types infer.
• Middleware order: devtools outermost, then persist, then immer innermost if used.
• Grouping actions under one stable actions object lets components select all of them without re-rendering, because the object identity never changes.
• The third argument to set under devtools is the action name shown in Redux DevTools; name actions so traces are readable.

Selectors

Pattern	Re-renders when	Use
useStore((s) => s.count)	count changes	default: one primitive per hook
useStore(useShallow((s) => ({ a: s.a, b: s.b })))	a or b changes	several values at once
useStore(useShallow((s) => s.items.map((i) => i.sku)))	the mapped array’s elements change	derived arrays
useStore((s) => s) or useStore()	anything changes	never in components

A selector that returns a new object or array on every call without useShallow causes “Maximum update depth exceeded” in v5 (v4 only re-rendered too much). Fix it with useShallow or by selecting primitives.

Expensive derived values: compute in the selector only if cheap; otherwise derive in the component with useMemo from narrowly selected inputs.

Slices for larger stores

import type { StateCreator } from "zustand";

type UiSlice = { sidebarOpen: boolean; toggleSidebar: () => void };
type EditorSlice = { selection: string[]; select: (ids: string[]) => void };
type Store = UiSlice & EditorSlice;

const createUiSlice: StateCreator<Store, [], [], UiSlice> = (set) => ({
  sidebarOpen: true,
  toggleSidebar: () => set((s) => ({ sidebarOpen: !s.sidebarOpen })),
});
const createEditorSlice: StateCreator<Store, [], [], EditorSlice> = (set) => ({
  selection: [],
  select: (ids) => set({ selection: ids }),
});

export const useAppStore = create<Store>()((...a) => ({ ...createUiSlice(...a), ...createEditorSlice(...a) }));

Apply middleware once on the combined store, not inside individual slices. Prefer several small independent stores over one large sliced store when the slices never read each other.

Server rendering (Next.js App Router and similar)

A module-level create() store is a singleton per server process: one user’s state can leak into another’s render. For state that is initialized per request or per user:

// src/stores/editor-store-provider.tsx
"use client";
import { createContext, useContext, useState } from "react";
import { createStore, useStore } from "zustand";

type EditorState = { docId: string; dirty: boolean; markDirty: () => void };
const createEditorStore = (docId: string) =>
  createStore<EditorState>()((set) => ({ docId, dirty: false, markDirty: () => set({ dirty: true }) }));

const EditorStoreContext = createContext<ReturnType<typeof createEditorStore> | null>(null);

export function EditorStoreProvider({ docId, children }: { docId: string; children: React.ReactNode }) {
  const [store] = useState(() => createEditorStore(docId));
  return <EditorStoreContext.Provider value={store}>{children}</EditorStoreContext.Provider>;
}

export function useEditorStore<T>(selector: (s: EditorState) => T) {
  const store = useContext(EditorStoreContext);
  if (!store) throw new Error("useEditorStore must be used inside EditorStoreProvider");
  return useStore(store, selector);
}

Persisted stores and SSR: the server renders defaults, the client rehydrates from storage, and the markup differs. Use skipHydration: true and call useCartStore.persist.rehydrate() in an effect, or render storage-dependent UI only after useCartStore.persist.hasHydrated() is true.

Testing

• Reset state between tests: capture const initial = useCartStore.getState() once and call useCartStore.setState(initial, true) in beforeEach (the true replaces instead of merging).
• Test actions through useCartStore.getState().actions.add("A") without rendering.
• For component tests, render with real stores; mock only the network layer.

Gotchas

• Calling set with a partial object merges one level deep only. Nested objects must be spread manually or updated with the immer middleware.
• Mutating state in place (s.items.push(x); return s) keeps the same reference, so selectors see no change and nothing re-renders.
• Persisting functions or class instances fails silently; partialize to plain data.
• Changing the persisted shape without bumping version and adding migrate breaks returning users’ state.
• Subscribing outside React (useCartStore.subscribe) needs the returned unsubscribe called on cleanup.

Verification

• Type-check passes with no any in store types.
• React DevTools “Highlight updates”: changing one store field re-renders only its subscribers.
• Redux DevTools shows named actions when devtools is used.
• Reload with persisted state from the previous version present; migration runs and the UI renders without hydration warnings.
• Tests reset the store and pass in random order.

Output

Document each store: purpose, fields, actions, exported selector hooks, persistence key and version, and whether it is a global singleton or per-request provider.