SKILL.md
🧠 Skill: zustand-expert
Description
Senior state architect specializing in Zustand v5 for modern React applications. Expert in solving hydration mismatches, preventing state leakage in SSR (Next.js), and implementing scalable architectures using the Slices Pattern and advanced middleware (Persist, Immer).
Core Priorities
- SSR Safety (Anti-Singleton): Preventing shared state between requests in Next.js by using per-request stores via React Context.
- Hydration Integrity: Managing persistence and asynchronous rehydration to ensure sub-100ms LCP without flickering.
- Modular Scalability: Enforcing the Slices Pattern for complex domain state.
- Performance Optimization: Strategic use of selectors and
useSyncExternalStore(Zustand v5 native).
🏆 Top 5 Gains in Zustand v5 (2026)
- Native
useSyncExternalStore: Full support for React 18/19 concurrent rendering with zero "tearing" issues. - Smaller Footprint: Dropped legacy support, leading to a leaner, faster bundle.
- Improved Type Safety: Native TypeScript support for combined stores and middleware.
- Context-Store Pattern: Official standard for SSR to avoid user-data leakage.
- Manual Rehydration Control:
skipHydration: truefor fine-grained control over when persisted state hits the UI.
Table of Contents & Detailed Guides
1. [SSR & Next.js 16 Pattern](./references/1-ssr-nextjs.md) — CRITICAL
- The Provider Pattern (Ref-based store creation)
- Preventing Singleton data leaks
- Initializing state from Server Props
2. [The Slices Pattern](./references/2-slices-pattern.md) — HIGH
- Modularizing large stores
- Type-safe combined states
- Sharing state between slices
3. [Persistence & Hydration](./references/3-persistence.md) — HIGH
persistmiddleware withskipHydration- Migration strategies for schema changes
- Handling Hydration Mismatch in Next.js
4. [Middleware & Immutability](./references/4-middleware.md) — MEDIUM
immerfor complex nested state- Custom middleware for logging/analytics
- Testing stores with Vitest/Jest
Quick Reference: The "Do's" and "Don'ts"
| Don't | Do |
|---|---|
export const useStore = create(...) |
Use StoreContext for SSR |
| Monolithic store file | Use Slices Pattern |
useStore(state => state) (Full object) |
Use Atomic Selectors (state.id) |
| Direct Mutation | Use immer middleware or functional updates |
useEffect for hydration sync |
Use persist with skipHydration |
| Store read in RSC | Use Props to pass data to Client Components |
Optimized for Zustand v5 and React 19.2+. Updated: January 22, 2026 - 15:03