Skill de Gestión de State con Zustand - Una receta de skill de Claude Code para construir state global escalable con Zustand

---
name: zustand-state-management
description: "Construcción de state global escalable y performante con Zustand y TypeScript. Úsalo cuando te pidan: ayuda con zustand, state global, patrón de store, gestión de state, selectores de zustand, middleware de zustand, persist de zustand, SSR con zustand."
allowed-tools: "Read, Write, Edit, Glob, Grep, Bash(npm:*), Bash(npx:*), Agent"
---
 
# Gestión de State con Zustand
 
Eres un experto en Zustand. Ayuda a los desarrolladores a construir gestión de state escalable, performante y bien tipada.
 
## Reglas de Arquitectura de Stores
 
1. **Un store por dominio** - store de auth, store de carrito, store de UI. Nunca un store gigante.
2. **State plano** - Evita objetos profundamente anidados. Normaliza los datos como en una base de datos.
3. **Coloca las acciones junto al state** - Mantén las acciones en el mismo store que el state que modifican.
4. **Usa selectores** - Nunca te suscribas al store completo. Selecciona siempre los datos mínimos necesarios.
5. **Deriva, no almacenes** - Los valores calculados deben derivarse en selectores, no almacenarse.
 
## Patrones Principales
 
### Store Básico con TypeScript
```tsx
import \{ create \} from "zustand";
 
interface CounterState \{
  count: number;
  increment: () => void;
  decrement: () => void;
  reset: () => void;
\}
 
const useCounterStore = create<CounterState>((set) => (\{
  count: 0,
  increment: () => set((state) => (\{ count: state.count + 1 \})),
  decrement: () => set((state) => (\{ count: state.count - 1 \})),
  reset: () => set(\{ count: 0 \}),
\}));

// MAL - se suscribe al store completo, re-renderiza con CUALQUIER cambio
function Component() \{
  const store = useCounterStore();
  return <span>\{store.count\}</span>;
\}
 
// BIEN - se suscribe solo a count
function Component() \{
  const count = useCounterStore((state) => state.count);
  return <span>\{count\}</span>;
\}
 
// BIEN - múltiples valores con comparación superficial
import \{ useShallow \} from "zustand/react/shallow";
 
function Component() \{
  const \{ count, increment \} = useCounterStore(
    useShallow((state) => (\{ count: state.count, increment: state.increment \}))
  );
  return <button onClick=\{increment\}>\{count\}</button>;
\}
 
// BIEN - referencia estable de acción (las acciones nunca cambian)
function Component() \{
  const increment = useCounterStore((state) => state.increment);
  // la referencia de increment es estable, sin re-renderizados por otros cambios de state
\}

interface AuthSlice \{
  user: User | null;
  login: (credentials: Credentials) => Promise<void>;
  logout: () => void;
\}
 
interface CartSlice \{
  items: CartItem[];
  addItem: (item: CartItem) => void;
  removeItem: (id: string) => void;
  total: () => number;
\}
 
const createAuthSlice: StateCreator<AuthSlice & CartSlice, [], [], AuthSlice> = (
  set
) => (\{
  user: null,
  login: async (credentials) => \{
    const user = await api.login(credentials);
    set(\{ user \});
  \},
  logout: () => set(\{ user: null \}),
\});
 
const createCartSlice: StateCreator<AuthSlice & CartSlice, [], [], CartSlice> = (
  set,
  get
) => (\{
  items: [],
  addItem: (item) => set((state) => (\{ items: [...state.items, item] \})),
  removeItem: (id) =>
    set((state) => (\{ items: state.items.filter((i) => i.id !== id) \})),
  total: () => get().items.reduce((sum, item) => sum + item.price, 0),
\});
 
const useStore = create<AuthSlice & CartSlice>()((...args) => (\{
  ...createAuthSlice(...args),
  ...createCartSlice(...args),
\}));

import \{ persist, createJSONStorage \} from "zustand/middleware";
 
const useSettingsStore = create<SettingsState>()(
  persist(
    (set) => (\{
      theme: "light" as const,
      language: "en",
      setTheme: (theme: "light" | "dark") => set(\{ theme \}),
      setLanguage: (language: string) => set(\{ language \}),
    \}),
    \{
      name: "settings-storage",
      storage: createJSONStorage(() => localStorage),
      partialize: (state) => (\{
        theme: state.theme,
        language: state.language,
      \}), // Solo persistir estos campos, no las acciones
    \}
  )
);

import \{ devtools \} from "zustand/middleware";
 
const useStore = create<StoreState>()(
  devtools(
    (set) => (\{
      count: 0,
      increment: () =>
        set(
          (state) => (\{ count: state.count + 1 \}),
          false,
          "increment" // nombre de la acción en devtools
        ),
    \}),
    \{ name: "MyStore" \}
  )
);

import \{ immer \} from "zustand/middleware/immer";
 
const useTodoStore = create<TodoState>()(
  immer((set) => (\{
    todos: [],
    toggleTodo: (id: string) =>
      set((state) => \{
        const todo = state.todos.find((t) => t.id === id);
        if (todo) todo.completed = !todo.completed; // la mutación directa es segura con immer
      \}),
    addTodo: (text: string) =>
      set((state) => \{
        state.todos.push(\{ id: crypto.randomUUID(), text, completed: false \});
      \}),
  \}))
);

const useStore = create<StoreState>()(
  devtools(
    persist(
      immer((set) => (\{
        // definición del store
      \})),
      \{ name: "my-store" \}
    ),
    \{ name: "MyStore" \}
  )
);
// Orden: immer (más interno) -> persist -> devtools (más externo)

// stores/counter-store.ts
import \{ create \} from "zustand";
 
interface CounterState \{
  count: number;
  increment: () => void;
\}
 
export const useCounterStore = create<CounterState>((set) => (\{
  count: 0,
  increment: () => set((state) => (\{ count: state.count + 1 \})),
\}));
 
// Para evitar desincronización de hidratación con el middleware persist:
// components/HydrationGuard.tsx
"use client";
 
import \{ useEffect, useState \} from "react";
 
export function HydrationGuard(\{ children \}: \{ children: React.ReactNode \}) \{
  const [hydrated, setHydrated] = useState(false);
  useEffect(() => setHydrated(true), []);
  return hydrated ? <>\{children\}</> : null; // o un skeleton
\}

interface ProductState \{
  products: Product[];
  loading: boolean;
  error: string | null;
  fetchProducts: () => Promise<void>;
\}
 
const useProductStore = create<ProductState>((set) => (\{
  products: [],
  loading: false,
  error: null,
  fetchProducts: async () => \{
    set(\{ loading: true, error: null \});
    try \{
      const products = await api.getProducts();
      set(\{ products, loading: false \});
    \} catch (error) \{
      set(\{ error: (error as Error).message, loading: false \});
    \}
  \},
\}));

import \{ renderHook, act \} from "@testing-library/react";
import \{ useCounterStore \} from "./counter-store";
 
// Restablecer el store entre pruebas
beforeEach(() => \{
  useCounterStore.setState(\{ count: 0 \});
\});
 
test("increment aumenta count", () => \{
  const \{ result \} = renderHook(() =>
    useCounterStore((state) => (\{
      count: state.count,
      increment: state.increment,
    \}))
  );
 
  act(() => result.current.increment());
  expect(result.current.count).toBe(1);
\});
 
// Probar el store directamente sin React
test("el store funciona sin componentes", () => \{
  const \{ getState \} = useCounterStore;
  expect(getState().count).toBe(0);
  getState().increment();
  expect(getState().count).toBe(1);
\});

mkdir -p .claude/skills/zustand-state-management
# Pega el contenido de la Receta en .claude/skills/zustand-state-management/SKILL.md