Zustand Pro -- State Management for Next.js 16

When to Use

Trigger on any mention of: zustand, global state, store, state management, persist middleware, immer, devtools, CV editor state, multi-step form state, undo/redo.

Reference Files

Load the relevant reference file(s) based on the task:

File	Lines	Content
references/setup.md	~65	Version compatibility matrix (v4/v5), breaking changes, React 19 notes, install, project structure
references/core-api.md	~100	create, createStore, useStore, setState, subscribe, selectors
references/nextjs-patterns.md	~190	3 patterns: global store, per-request context provider (SSR), hydration-safe persist, server component rules
references/typescript.md	~115	Basic typed store, middleware typing, slices pattern (large stores), typed selectors
references/middleware.md	~195	persist, devtools, immer, subscribeWithSelector, combine, composition order
references/errors-001-010.md	~200	ZST-001 to ZST-010: hydration, infinite re-render, server component, state sync, TS middleware, SSR storage, useShallow, devtools, persist schema, async actions
references/errors-011-020.md	~175	ZST-011 to ZST-020: missing provider, immer import, fast refresh, slices+middleware TS, persist+immer merge, React Compiler naming, subscribeWithSelector, setState replace, window undefined, stale closure
references/cviet-patterns.md	~190	Full multi-step CV editor store with devtools+subscribeWithSelector+immer, navigation, CRUD for all CV sections, AI patch, saving
references/cviet-hooks.md	~170	Auto-save with debounce, undo/redo (zundo), AI panel integration, unsaved changes warning
references/performance.md	~130	Atomic selectors, useShallow, stable action refs, transient updates, computed/derived state, selector extraction
references/testing.md	~155	Jest auto-reset mock, Vitest auto-reset mock, store direct testing, component testing, pre-set state testing
references/anti-patterns.md	~170	6 anti-patterns (server component store, full store select, store in component, direct mutation, server state, missing useShallow) + 3 gotchas (middleware order, Set/Map persist, getState reactivity)
references/ecosystem.md	~85	Zustand vs Redux vs Jotai comparison, why Zustand for CViet, third-party middleware (zundo, zustand-computed, zukeeper), key links, quick reference card

Error Quick Lookup

ID	Error	Fix
ZST-001	Hydration mismatch with persist	skipHydration + useHydratedStore hook
ZST-002	Infinite re-render (v5)	Use useShallow or stable selector
ZST-003	Hook in Server Component	Move to Client Component with 'use client'
ZST-004	State not updating across components	Immutable update or check import path
ZST-005	TypeScript error with middleware	Use curried create<Type>()(...) form
ZST-006	Persist storage unavailable (SSR)	Guard with typeof window check
ZST-007	useShallow import not found	Import from zustand/shallow (v5)
ZST-008	DevTools not showing store	Add devtools middleware with name
ZST-009	Persist overwrites new fields	Add version + migrate to persist config
ZST-010	Async action not updating	Use set() after await, not direct mutation
ZST-011	Cannot read getState (undefined)	Wrap component tree in Provider
ZST-012	Immer not working	Import from zustand/middleware/immer
ZST-013	Multiple store instances (dev)	Expected in dev; use persist for preservation
ZST-014	TS error with slices + middleware	Declare middleware mutators in StateCreator
ZST-015	Persist + immer deep merge conflict	Custom merge function with structuredClone
ZST-016	React Compiler use prefix warning	Name stores useXxxStore
ZST-017	subscribeWithSelector fires always	Provide equalityFn or stable selector
ZST-018	setState replace missing fields (v5)	Provide ALL fields or use partial update
ZST-019	"window is not defined"	Guard persist storage with typeof window
ZST-020	Stale closure in useEffect	Use subscribe or getState() in effect

Key Patterns

Store Creation (Next.js 16)

// src/stores/cv-editor-store.ts
'use client'  // Not needed for store file, but consumers must be client

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

// Middleware order matters: devtools(persist(immer(...)))

Hydration-Safe Persist

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

const useStore = create(persist((...) => ({...}), {
  name: 'cv-draft',
  skipHydration: true,  // Critical for Next.js SSR
}))

// In client component:
useEffect(() => { useStore.persist.rehydrate() }, [])

useShallow for Multi-Value Selectors

import { useShallow } from 'zustand/shallow'

const { name, email } = useStore(
  useShallow((s) => ({ name: s.name, email: s.email }))
)

Middleware Composition Order

devtools -> subscribeWithSelector -> persist -> immer -> stateCreator