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