playbooks

home / skills / yuniorglez / gemini-elite-core / zustand-expert

zustand-expert skill

/skills/zustand-expert

This skill helps you master zustand v5 for SSR-safe, scalable state with slices pattern, hydration reliability, and per-request stores.

npx playbooks add skill yuniorglez/gemini-elite-core --skill zustand-expert

Review the files below or copy the command above to add this skill to your agents.

Files (5)
SKILL.md
2.9 KB
---
name: zustand-expert
id: zustand-expert
version: 1.2.0
description: "Senior State Architect for React 19 and Next.js 16.1+ applications. Specialist in Zustand v5, SSR-safe stores, and slices pattern for large-scale state management."
---

# 🧠 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
1.  **SSR Safety (Anti-Singleton)**: Preventing shared state between requests in Next.js by using per-request stores via React Context.
2.  **Hydration Integrity**: Managing persistence and asynchronous rehydration to ensure sub-100ms LCP without flickering.
3.  **Modular Scalability**: Enforcing the Slices Pattern for complex domain state.
4.  **Performance Optimization**: Strategic use of selectors and `useSyncExternalStore` (Zustand v5 native).

## 🏆 Top 5 Gains in Zustand v5 (2026)

1.  **Native `useSyncExternalStore`**: Full support for React 18/19 concurrent rendering with zero "tearing" issues.
2.  **Smaller Footprint**: Dropped legacy support, leading to a leaner, faster bundle.
3.  **Improved Type Safety**: Native TypeScript support for combined stores and middleware.
4.  **Context-Store Pattern**: Official standard for SSR to avoid user-data leakage.
5.  **Manual Rehydration Control**: `skipHydration: true` for 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**
- `persist` middleware with `skipHydration`
- Migration strategies for schema changes
- Handling Hydration Mismatch in Next.js

### 4. [Middleware & Immutability](./references/4-middleware.md) — **MEDIUM**
- `immer` for 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*

Overview

This skill packages senior-level guidance for building scalable, SSR-safe Zustand v5 stores in React 19 and Next.js 16.1+ apps. It focuses on preventing request-scoped state leakage, preserving hydration integrity, and applying the Slices Pattern for large codebases. The content targets engineers designing high-performance, type-safe client and server interactions.

How this skill works

I describe concrete architectures and patterns: per-request stores via a StoreContext provider to avoid singletons in Next.js, atomic selectors with useSyncExternalStore for performance, and manual rehydration control using persist middleware and skipHydration. The material includes middleware recommendations (immer, custom logging), migration strategies for persisted schemas, and testing tips for predictable SSR behavior.

When to use it

  • Building Next.js apps that render on the server and must avoid shared user state across requests
  • Scaling a monolithic Zustand store into maintainable domain slices across teams
  • Improving hydration performance and removing UI flicker on first paint
  • Migrating legacy Zustand setups to v5 with stronger TypeScript guarantees
  • Implementing persistence with deterministic rehydration timing to meet LCP budgets

Best practices

  • Never export a single create(...) store for SSR; create per-request stores injected via React Context
  • Use the Slices Pattern to split domain logic and combine stores with typed interfaces
  • Prefer atomic selectors (state.x) and native useSyncExternalStore to minimize re-renders
  • Apply persist with skipHydration and explicit rehydrate control to avoid hydration mismatch
  • Use immer or immutable updates for complex nested state and write focused middleware for telemetry

Example use cases

  • Auth + session stores scoped per request to prevent cross-user data leaks on server renders
  • E-commerce product and cart slices combined into a typed root store with isolated selectors
  • Progressive rehydration: show skeleton UI while persisted data rehydrates below 100ms LCP
  • Schema migrations for persisted state with versioned transforms and fallback handling
  • Testing store behavior in SSR flows using Vitest or Jest with mocked per-request providers

FAQ

How do I prevent shared state between concurrent Next.js requests?

Create a new store instance per request and provide it through a StoreContext. Avoid exporting a global create(...) hook directly.

When should I use skipHydration?

Use skipHydration when you need precise control over when persisted state updates mount-time UI to prevent flicker and hydration mismatch; rehydrate manually once the client is ready.