Covers skipHydration with the persist middleware plus manual rehydration in useEffect to avoid SSR mismatches, useShallow for array/object selectors, and SOLID file organization (store.ts, store-provider.tsx, use-store.ts). States explicitly that Zustand is Client-Components-only — never used in Server Components (fetch data directly there instead) and never used to persist auth tokens (use httpOnly cookies). Does not cover server state caching (see nextjs-tanstack-query for that).
Zustand for Next.js 16
Minimal, scalable state management with React 18+ useSyncExternalStore.
Agent Workflow (MANDATORY)
Before ANY implementation, spawn 3 agents in parallel, one Agent call each with a name:
- fuse-ai-pilot:explore-codebase - Analyze existing stores and state patterns
- fuse-ai-pilot:research-expert - Verify latest Zustand v5 docs via Context7/Exa
- mcp__context7__query-docs - Check middleware and TypeScript patterns
After implementation, run fuse-ai-pilot:sniper for validation.
Overview
When to Use
- Managing client-side state in Next.js App Router applications
- Need global state across Client Components only
- Persisting state to localStorage/sessionStorage
- Building UI state (modals, sidebars, theme, cart)
- Replacing React Context for complex state
Why Zustand v5
| Feature |
Benefit |
| Minimal API |
Simple create() function, no boilerplate |
| React 18 native |
useSyncExternalStore, no shims needed |
| TypeScript first |
Full inference with currying pattern |
| Middleware stack |
devtools, persist, immer composable |
| Bundle size |
~2KB gzipped, smallest state library |
| No providers |
Direct store access, no Context wrapper |
Critical Rules
- Client Components ONLY - Never use Zustand in Server Components
- Context pattern for App Router - Avoid global stores (request isolation)
- useShallow for arrays/objects - Prevent unnecessary re-renders
- skipHydration with persist - Required for SSR compatibility
- Currying syntax v5 -
create<State>()((set) => ({...}))
- SOLID paths - Stores in
modules/[feature]/src/stores/
SOLID Architecture
Module Structure
Stores organized by feature module:
modules/cores/stores/ - Shared stores (theme, ui)
modules/auth/src/stores/ - Auth state
modules/cart/src/stores/ - Cart state
modules/[feature]/src/interfaces/ - Store types
File Organization
| File |
Purpose |
Max Lines |
store.ts |
Store creation with create() |
50 |
store.interface.ts |
TypeScript interfaces |
30 |
store-provider.tsx |
Context provider (App Router) |
40 |
use-store.ts |
Custom hook with selector |
20 |
Key Concepts
Store Creation (v5 Syntax)
Double parentheses required for TypeScript inference. Currying pattern ensures full type safety.
Context-Based Stores
For Next.js App Router, wrap stores in Context to prevent request-sharing. Use createStore from zustand/vanilla with useRef for initialization.
Middleware Composition
Stack middlewares: devtools → persist → immer. Order matters for TypeScript types.
Hydration Handling
Use skipHydration: true with persist middleware. Manually rehydrate in useEffect to avoid SSR mismatches.
Reference Guide
| Need |
Reference |
| Initial setup |
installation.md |
| Store patterns |
store-patterns.md |
| SSR/Hydration |
hydration.md |
| Middleware |
middleware.md |
| Next.js App Router |
nextjs-integration.md |
| TypeScript |
typescript.md |
| Slices pattern |
slices.md |
| Auto selectors |
auto-selectors.md |
| Reset state |
reset-state.md |
| Subscribe API |
subscribe-api.md |
| Testing |
testing.md |
| Migration v4→v5 |
migration-v5.md |
Best Practices
- Selector pattern - Always use
useStore((s) => s.field) for performance
- useShallow - Wrap array/object selectors to prevent re-renders
- Separate stores - One store per domain (auth, cart, ui, theme)
- Server data elsewhere - Use TanStack Query for server state
- DevTools in dev only - Wrap devtools in process.env check
- Partialize persist - Only persist necessary fields, never tokens
Forbidden Patterns
| Pattern |
Reason |
Alternative |
| Global stores in App Router |
Request sharing between users |
Context-based stores |
| Zustand in Server Components |
No React hooks in RSC |
Fetch data directly |
| Persisting auth tokens |
Security vulnerability |
httpOnly cookies |
| Without useShallow on objects |
Excessive re-renders |
useShallow(selector) |
| v4 syntax |
TypeScript inference broken |
v5 currying create<T>()() |
1---2name: nextjs-zustand3description: Use when implementing global state, stores, persist, or hydration in Next.js 16 App Router Client Components with Zustand v5.4versions:5 zustand: 5.06 react: 197 nextjs: 168user-invocable: true9references: references/installation.md, references/store-patterns.md, references/hydration.md, references/middleware.md, references/nextjs-integration.md, references/typescript.md, references/slices.md, references/auto-selectors.md, references/reset-state.md, references/subscribe-api.md, references/testing.md, references/migration-v5.md10related-skills: nextjs-16, nextjs-tanstack-form, solid-nextjs11metadata:12 source: https://skillmd.com/skills/fusengine/nextjs-zustand13---1415<objective>16Implements Zustand v5 client-side state management in Next.js 16 App Router: the v5 currying syntax (`create<State>()((set) => ({...}))`), Context-based stores built with `createStore` from `zustand/vanilla` + `useRef` (required in App Router to avoid state leaking between requests — never a global store), and middleware composition (devtools → persist → immer, order-sensitive for TypeScript).1718Covers `skipHydration` with the persist middleware plus manual rehydration in `useEffect` to avoid SSR mismatches, `useShallow` for array/object selectors, and SOLID file organization (`store.ts`, `store-provider.tsx`, `use-store.ts`). States explicitly that Zustand is Client-Components-only — never used in Server Components (fetch data directly there instead) and never used to persist auth tokens (use httpOnly cookies). Does not cover server state caching (see nextjs-tanstack-query for that).19</objective>2021# Zustand for Next.js 162223Minimal, scalable state management with React 18+ useSyncExternalStore.2425## Agent Workflow (MANDATORY)2627Before ANY implementation, spawn 3 agents in parallel, one `Agent` call each with a `name`:28291. **fuse-ai-pilot:explore-codebase** - Analyze existing stores and state patterns302. **fuse-ai-pilot:research-expert** - Verify latest Zustand v5 docs via Context7/Exa313. **mcp__context7__query-docs** - Check middleware and TypeScript patterns3233After implementation, run **fuse-ai-pilot:sniper** for validation.3435---3637## Overview3839### When to Use4041- Managing client-side state in Next.js App Router applications42- Need global state across Client Components only43- Persisting state to localStorage/sessionStorage44- Building UI state (modals, sidebars, theme, cart)45- Replacing React Context for complex state4647### Why Zustand v54849| Feature | Benefit |50|---------|---------|51| Minimal API | Simple create() function, no boilerplate |52| React 18 native | useSyncExternalStore, no shims needed |53| TypeScript first | Full inference with currying pattern |54| Middleware stack | devtools, persist, immer composable |55| Bundle size | ~2KB gzipped, smallest state library |56| No providers | Direct store access, no Context wrapper |5758---5960## Critical Rules61621. **Client Components ONLY** - Never use Zustand in Server Components632. **Context pattern for App Router** - Avoid global stores (request isolation)643. **useShallow for arrays/objects** - Prevent unnecessary re-renders654. **skipHydration with persist** - Required for SSR compatibility665. **Currying syntax v5** - `create<State>()((set) => ({...}))`676. **SOLID paths** - Stores in `modules/[feature]/src/stores/`6869---7071## SOLID Architecture7273### Module Structure7475Stores organized by feature module:7677- `modules/cores/stores/` - Shared stores (theme, ui)78- `modules/auth/src/stores/` - Auth state79- `modules/cart/src/stores/` - Cart state80- `modules/[feature]/src/interfaces/` - Store types8182### File Organization8384| File | Purpose | Max Lines |85|------|---------|-----------|86| `store.ts` | Store creation with create() | 50 |87| `store.interface.ts` | TypeScript interfaces | 30 |88| `store-provider.tsx` | Context provider (App Router) | 40 |89| `use-store.ts` | Custom hook with selector | 20 |9091---9293## Key Concepts9495### Store Creation (v5 Syntax)9697Double parentheses required for TypeScript inference. Currying pattern ensures full type safety.9899### Context-Based Stores100101For Next.js App Router, wrap stores in Context to prevent request-sharing. Use `createStore` from `zustand/vanilla` with `useRef` for initialization.102103### Middleware Composition104105Stack middlewares: devtools → persist → immer. Order matters for TypeScript types.106107### Hydration Handling108109Use `skipHydration: true` with persist middleware. Manually rehydrate in useEffect to avoid SSR mismatches.110111---112113## Reference Guide114115| Need | Reference |116|------|-----------|117| Initial setup | [installation.md](references/installation.md) |118| Store patterns | [store-patterns.md](references/store-patterns.md) |119| SSR/Hydration | [hydration.md](references/hydration.md) |120| Middleware | [middleware.md](references/middleware.md) |121| Next.js App Router | [nextjs-integration.md](references/nextjs-integration.md) |122| TypeScript | [typescript.md](references/typescript.md) |123| Slices pattern | [slices.md](references/slices.md) |124| Auto selectors | [auto-selectors.md](references/auto-selectors.md) |125| Reset state | [reset-state.md](references/reset-state.md) |126| Subscribe API | [subscribe-api.md](references/subscribe-api.md) |127| Testing | [testing.md](references/testing.md) |128| Migration v4→v5 | [migration-v5.md](references/migration-v5.md) |129130---131132## Best Practices1331341. **Selector pattern** - Always use `useStore((s) => s.field)` for performance1352. **useShallow** - Wrap array/object selectors to prevent re-renders1363. **Separate stores** - One store per domain (auth, cart, ui, theme)1374. **Server data elsewhere** - Use TanStack Query for server state1385. **DevTools in dev only** - Wrap devtools in process.env check1396. **Partialize persist** - Only persist necessary fields, never tokens140141---142143## Forbidden Patterns144145| Pattern | Reason | Alternative |146|---------|--------|-------------|147| Global stores in App Router | Request sharing between users | Context-based stores |148| Zustand in Server Components | No React hooks in RSC | Fetch data directly |149| Persisting auth tokens | Security vulnerability | httpOnly cookies |150| Without useShallow on objects | Excessive re-renders | `useShallow(selector)` |151| v4 syntax | TypeScript inference broken | v5 currying `create<T>()()` |