Version history: Zustand
v1
scan: pass2026-08-11 — Ingested from sourceInitial version.
v2
currentscan: pass2026-11-02 — Currency pass 2026-11-01: completed the async-actions example that was truncated at source; replaced the removed v4 useStore(selector, shallow) form with useShallow from zustand/react/shallow; made create<T>()(...) consistent everywhere; globs changed from js/jsx to ts/tsx to match the TypeScript examples; frontmatter globs made valid YAML.---- description: Definitive guidelines for using Zustand in React projects, focusing on type safety, modularity, performance, and maintainability with practical code examples. - globs: **/*.{js,jsx}+ description: "Zustand v5 patterns for React and TypeScript projects: typed stores, slices, functional updates, useShallow selectors, middleware, and async actions." + globs: "**/*.{ts,tsx}" + alwaysApply: false --- # zustand Best Practices - Zustand is our go-to for global state management due to its minimal API and built-in performance optimizations. This guide outlines the definitive patterns for using Zustand effectively in our projects, ensuring type safety, modularity, and optimal performance.+ Zustand is our go-to for global state management due to its minimal API and built-in performance optimizations. This guide outlines the definitive patterns for using Zustand (v5) effectively in our projects, ensuring type safety, modularity, and optimal performance. ## 1. Typed Store Shape (TypeScript First) - Always define explicit TypeScript interfaces for your store's state and actions. This provides invaluable type safety and auto-completion across the application, preventing common runtime errors.+ Always define explicit TypeScript interfaces for your store's state and actions. This provides invaluable type safety and auto-completion across the application, preventing common runtime errors. Use the curried form `create<T>()(...)` so middleware can be added later without changing the type signature. ❌ BAD: Untyped store, prone to runtime errors ```typescript import { create } from 'zustand'; const useStore = create((set) => ({ count: 0, increment: () => set((state) => ({ count: state.count + 1 })), })); ``` ✅ GOOD: Fully typed store for robust development ```typescript import { create } from 'zustand'; interface CounterState { count: number; increment: () => void; decrement: () => void; } - const useCounterStore = create<CounterState>((set) => ({+ const useCounterStore = create<CounterState>()((set) => ({ count: 0, increment: () => set((state) => ({ count: state.count + 1 })), decrement: () => set((state) => ({ count: state.count - 1 })), })); ``` ## 2. Slice-Based Organization For scalable applications, organize your store into logical "slices" (e.g., `authSlice`, `uiSlice`). This keeps concerns separated, improves readability, and makes testing easier. Compose these slices into a single root store. `src/store/types.ts`: ```typescript import { StateCreator } from 'zustand'; // Define individual slice interfaces export interface AuthSlice { user: { id: string; name: string } | null; token: string | null; login: (user: { id: string; name: string }, token: string) => void; logout: () => void; } export interface UISlice { isLoading: boolean; setLoading: (loading: boolean) => void; } // Combine all slice interfaces into the global AppState export type AppState = AuthSlice & UISlice; // Type for creating slices that will be composed into AppState export type AppStateCreator<T> = StateCreator<AppState, [], [], T>; ``` `src/store/slices/createAuthSlice.ts`: ```typescript import { AppStateCreator, AuthSlice } from '../types'; export const createAuthSlice: AppStateCreator<AuthSlice> = (set) => ({ user: null, token: null, login: (user, token) => set({ user, token }), logout: () => set({ user: null, token: null }), }); ``` `src/store/slices/createUISlice.ts`: ```typescript import { AppStateCreator, UISlice } from '../types'; export const createUISlice: AppStateCreator<UISlice> = (set) => ({ isLoading: false, setLoading: (loading) => set({ isLoading: loading }), }); ``` `src/store/useAppStore.ts`: ```typescript import { create } from 'zustand'; import { AppState } from './types'; import { createAuthSlice } from './slices/createAuthSlice'; import { createUISlice } from './slices/createUISlice'; export const useAppStore = create<AppState>()((...a) => ({ ...createAuthSlice(...a), ...createUISlice(...a), })); ``` ## 3. Naming Conventions Follow consistent naming for clarity and discoverability. * **Store Hook**: `use[Feature]Store` or `useAppStore` for the root. * **Actions**: Verb-oriented (e.g., `increment`, `setUser`, `fetchData`). * **Store Files**: Located under `src/store/` or `src/features/[feature]/store.ts`. * **Exports**: Only export the custom hook, never the raw `create` object. ❌ BAD: Inconsistent naming, exposing raw store ```typescript- // store.js - export const myStore = create(...); // Exposes raw store+ // store.ts + export const myStore = create<AppState>()(...); // Exposes raw store export const useMyStore = myStore; // Bad naming, use `useMyStore` as the primary hook - // component.jsx+ // component.tsx myStore.setState({ ... }); // Direct mutation outside hook, bypasses React lifecycle ``` ✅ GOOD: Clear, consistent, and encapsulated ```typescript // src/store/useAppStore.ts- export const useAppStore = create<AppState>(...);+ export const useAppStore = create<AppState>()(...); // src/features/auth/useAuthStore.ts (if using feature-specific stores)- export const useAuthStore = create<AuthSlice>(...);+ export const useAuthStore = create<AuthSlice>()(...); // component.tsx import { useAppStore } from 'src/store/useAppStore';- const { user, login } = useAppStore();+ const user = useAppStore((state) => state.user); + const login = useAppStore((state) => state.login); ``` ## 4. Functional Updates to Prevent Stale Closures Always use functional updates (`set(state => ...)`) when an action's new state depends on the current state. This prevents issues with stale closures in asynchronous operations or rapid updates. ❌ BAD: Potential stale closure, especially in async operations ```typescript- const useCounterStore = create<CounterState>((set, get) => ({+ const useCounterStore = create<CounterState>()((set, get) => ({ count: 0, // ... incrementAsync: async () => { await someAsyncOperation(); const currentCount = get().count; // 'currentCount' might be outdated if another update occurred set({ count: currentCount + 1 }); }, })); ``` ✅ GOOD: Robust functional update, `state` is always the latest ```typescript- const useCounterStore = create<CounterState>((set) => ({+ const useCounterStore = create<CounterState>()((set) => ({ count: 0, // ... incrementAsync: async () => { await someAsyncOperation(); set((state) => ({ count: state.count + 1 })); }, })); ``` - ## 5. Selectors and Shallow Comparison for Performance+ ## 5. Selectors and `useShallow` for Performance - Consume only the necessary parts of the state using selectors. For objects or arrays, use `shallow` (or a custom equality function) to prevent unnecessary re-renders when only nested properties change.+ Consume only the necessary parts of the state using selectors. A selector that returns a new object or array on every call re-renders on every store change; wrap it in `useShallow` (from `zustand/react/shallow`) so the component only re-renders when the selected values actually change. The old second-argument form `useStore(selector, shallow)` was removed in Zustand v5. ❌ BAD: Re-renders component on any state change in the store ```typescript const MyComponent = () => { const { user, token } = useAppStore(); // Re-renders if any part of AppState changes // ... };+ + const Legacy = () => { + // v4 API; the second argument no longer exists in v5 and the fresh object + // returned by the selector re-renders on every change + const { name, email } = useAppStore( + (state) => ({ name: state.user?.name, email: state.user?.email }), + shallow + ); + // ... + }; ``` - ✅ GOOD: Optimized re-renders with selectors and `shallow`+ ✅ GOOD: Optimized re-renders with selectors and `useShallow` ```typescript- import { shallow } from 'zustand/shallow';+ import { useShallow } from 'zustand/react/shallow'; import { useAppStore } from 'src/store/useAppStore'; const UserProfile = () => { // Only re-renders if user.name or user.email changes const { name, email } = useAppStore(- (state) => ({ name: state.user?.name, email: state.user?.email }), - shallow+ useShallow((state) => ({ name: state.user?.name, email: state.user?.email })) ); // ... }; const AuthStatus = () => {- // Only re-renders if token changes+ // Primitive selector: no useShallow needed, only re-renders if token changes const token = useAppStore((state) => state.token); // ... }; ``` ## 6. Essential Middleware Usage Leverage Zustand's middleware for common concerns like persistence, devtools integration, and immutable updates. * **`persist`**: For local storage or IndexedDB. Always provide a `name` and consider `version` for migrations. * **`devtools`**: Integrate with Redux DevTools. Enable only in development. * **`immer`**: For simplified immutable updates, especially with deeply nested objects. ```typescript import { create } from 'zustand'; import { persist, devtools, createJSONStorage } from 'zustand/middleware'; import { immer } from 'zustand/middleware/immer'; interface SettingsState { theme: 'light' | 'dark'; notifications: { enabled: boolean; sound: boolean }; setTheme: (theme: 'light' | 'dark') => void; toggleNotifications: () => void; toggleNotificationSound: () => void; } const useSettingsStore = create<SettingsState>()( devtools( // Enable devtools for debugging persist( // Persist state to storage immer((set) => ({ // Use immer for easier immutable updates theme: 'light', notifications: { enabled: true, sound: true }, setTheme: (theme) => set({ theme }), toggleNotifications: () => set((state) => { state.notifications.enabled = !state.notifications.enabled; // Direct mutation with immer }), toggleNotificationSound: () => set((state) => { state.notifications.sound = !state.notifications.sound; // Direct mutation with immer }), })), { name: 'app-settings', // Unique name for storage key storage: createJSONStorage(() => localStorage), // Choose storage type version: 1, // Crucial for future migrations partialize: (state) => ({ theme: state.theme }), // Only persist 'theme' } ), { name: 'Settings Store', enabled: process.env.NODE_ENV === 'development' } // Devtools options ) ); ``` ## 7. Initializing Stores Outside Components - Declare your `create` calls at the module level (top of the file) to ensure a single, consistent store instance across your application. Never call `create` inside a React component.+ Declare your `create` calls at the module level (top of the file) to ensure a single, consistent store instance across your application. Never call `create` inside a React component. (For per-request stores in server-rendered apps such as Next.js, use `createStore` from `zustand/vanilla` inside a context provider instead of a module-level singleton.) ❌ BAD: Creates new store instance on every render ```typescript const MyComponent = () => { // This creates a NEW store instance every time MyComponent re-renders! const useLocalStore = create(() => ({ value: 0 })); const value = useLocalStore((state) => state.value); return <div>{value}</div>; }; ``` ✅ GOOD: Single store instance, declared once ```typescript // At the top of your store file (e.g., src/store/useCounterStore.ts)- const useCounterStore = create<CounterState>((set) => ({+ const useCounterStore = create<CounterState>()((set) => ({ count: 0, increment: () => set((state) => ({ count: state.count + 1 })), })); const MyComponent = () => { const count = useCounterStore((state) => state.count); return <div>{count}</div>; }; ``` ## 8. Asynchronous Actions - Handle asynchronous operations directly within your store actions. Zustand doesn't require special middleware for async, keeping the API simple and direct.+ Handle asynchronous operations directly within your store actions. Zustand doesn't require special middleware for async, keeping the API simple and direct. Track `loading` and `error` explicitly, and reset `error` at the start of each request. ```typescript interface UserState { user: { id: string; name: string } | null; loading: boolean; error: string | null; fetchUser: (userId: string) => Promise<void>; } - const useUserStore = create<UserState>((set) => ({+ const useUserStore = create<UserState>()((set) => ({ user: null, loading: false, error: null, fetchUser: async (userId) => { set({ loading: true, error: null }); try { const response = await fetch(`/api/users/${userId}`);- if (!response.ok) throw new Error('Failed+ if (!response.ok) throw new Error(`Failed to fetch user: ${response.status}`); + const user = (await response.json()) as { id: string; name: string }; + set({ user, loading: false }); + } catch (error) { + set({ + error: error instanceof Error ? error.message : 'Unknown error', + loading: false, + }); + } + }, + })); + ``` + + ```typescript + const UserCard = ({ userId }: { userId: string }) => { + const { user, loading, error, fetchUser } = useUserStore( + useShallow((state) => ({ + user: state.user, + loading: state.loading, + error: state.error, + fetchUser: state.fetchUser, + })) + ); + + useEffect(() => { + void fetchUser(userId); + }, [fetchUser, userId]); + + if (loading) return <Spinner />; + if (error) return <ErrorMessage message={error} />; + return <div>{user?.name}</div>; + }; + ``` + + For server data with caching, retries, and request deduplication, prefer a dedicated data-fetching library (e.g., TanStack Query) and keep Zustand for client-side UI state.