nextjs-zustand_skill

Overview

This skill provides a standardized Zustand v5 state management setup tuned for Next.js 16 App Router. It supplies TypeScript-safe store patterns, Client Component guidance, persist/hydration helpers, and a context-based approach to avoid request-sharing. Use it to implement minimal, performant global client state across modular features.

How this skill works

The skill scaffolds currying-based Zustand v5 stores, middleware stacks (devtools → persist → immer), and context wrappers suitable for the App Router. It enforces client-only usage, skipHydration for persist, and helper hooks (selectors, useShallow) to prevent unnecessary re-renders. It also recommends file layouts and initialization patterns using createStore from zustand/vanilla and useRef for safe per-request instantiation.

When to use it

• Managing client-side UI or domain state in Next.js App Router projects
• Sharing global state across Client Components without React Context boilerplate
• Persisting selective state to localStorage/sessionStorage with safe hydration
• Replacing complex React Context setups for performance and simplicity
• Implementing modular, SOLID-aligned stores per feature

Best practices

• Always use the v5 currying syntax: create<State>()((set) => ({})) for full TypeScript inference
• Wrap stores in a Context for App Router to avoid request sharing; initialize with createStore and useRef
• Use selector pattern: useStore(s => s.field) and useShallow for arrays/objects to avoid re-renders
• Compose middleware in order (devtools → persist → immer) and enable devtools only in development
• Persist only necessary fields (never store tokens); use skipHydration: true and rehydrate client-side in useEffect

Example use cases

• A theme store for client-only theme toggles and persisted preference
• UI store for modals, sidebars, and temporary UI flags across Client Components
• Cart store that persists items to localStorage while avoiding SSR mismatch
• Auth client state (non-sensitive flags only) managed per-request via Context-based store
• Feature-scoped stores in modules/cart or modules/auth following SOLID folder layout