nextjs-zustand

Original：🇺🇸 English

Translated

Zustand v5 state management for Next.js 16 App Router. Use when implementing global state, stores, persist, hydration, or client-side state in Client Components.

1installs

Sourcefusengine/agents

Added on2026-02-22

NPX Install

npx skill4agent add fusengine/agents nextjs-zustand

SKILL.md Content

View Translation Comparison →

Zustand for Next.js 16

Minimal, scalable state management with React 18+ useSyncExternalStore.

Agent Workflow (MANDATORY)

Before ANY implementation, use

TeamCreate

to spawn 3 agents:

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>()()`