Zustand State Management: patrones para aplicaciones complejas
Las primitivas de estado integradas de React (useState, useReducer, useContext) funcionan bien para el estado de la interfaz de usuario local y compartida, pero encuentran fricciones a escala: los proveedores de contexto vuelven a renderizar todo el árbol en cada cambio de estado, useReducer requiere una acción repetitiva detallada y la perforación de accesorios se vuelve inmanejable. Redux resuelve esto, pero a costa de una importante sobrecarga mental y repetitiva.
Zustand ocupa un término medio perfecto: 2,9 KB, sin proveedores, sin texto estándar, TypeScript primero y compatible con React DevTools. Destaca en el estado de la aplicación del lado del cliente (carritos de compras, estado de la barra lateral, datos de formularios de varios pasos, preferencias de la interfaz de usuario), mientras que TanStack Query maneja el estado del servidor. Esta guía cubre los patrones de Zustand v5 para aplicaciones de producción.
Conclusiones clave
- Zustand es para estado de sólo cliente; utilice TanStack Query para el estado del servidor: no superponga sus responsabilidades
- No se necesita contenedor de proveedor: la tienda es singleton a nivel de módulo, accesible desde cualquier lugar
- Utilice el patrón de sectores para tiendas grandes: componga varios creadores de sectores en una llamada
create()- El middleware
immerpermite la sintaxis de mutación directa dentro de las acciones (sin operadores extendidos)persistmiddleware conlocalStorageosessionStoragepara el estado de sesión cruzada- El middleware
devtoolsse integra con Redux DevTools Extension para la depuración de viajes en el tiempo- Los selectores con
useShallowevitan renderizaciones innecesarias de objetos iguales y poco profundos- Nunca almacene datos del servidor en Zustand: la invalidación se convierte en su problema
Tienda básica
// src/lib/stores/ui.store.ts
import { create } from 'zustand';
import { devtools } from 'zustand/middleware';
interface UiState {
// State
sidebarOpen: boolean;
theme: 'light' | 'dark' | 'system';
commandPaletteOpen: boolean;
activeModal: string | null;
// Actions
toggleSidebar: () => void;
setSidebarOpen: (open: boolean) => void;
setTheme: (theme: UiState['theme']) => void;
openModal: (modalId: string) => void;
closeModal: () => void;
toggleCommandPalette: () => void;
}
export const useUiStore = create<UiState>()(
devtools(
(set) => ({
sidebarOpen: true,
theme: 'system',
commandPaletteOpen: false,
activeModal: null,
toggleSidebar: () =>
set((state) => ({ sidebarOpen: !state.sidebarOpen }), false, 'toggleSidebar'),
setSidebarOpen: (open) =>
set({ sidebarOpen: open }, false, 'setSidebarOpen'),
setTheme: (theme) =>
set({ theme }, false, 'setTheme'),
openModal: (modalId) =>
set({ activeModal: modalId }, false, 'openModal'),
closeModal: () =>
set({ activeModal: null }, false, 'closeModal'),
toggleCommandPalette: () =>
set(
(state) => ({ commandPaletteOpen: !state.commandPaletteOpen }),
false,
'toggleCommandPalette'
),
}),
{ name: 'ui-store' }
)
);
// Usage in components — select only what you need
function Sidebar() {
const isOpen = useUiStore((state) => state.sidebarOpen);
const toggle = useUiStore((state) => state.toggleSidebar);
return (
<aside className={cn('sidebar', isOpen && 'sidebar--open')}>
<button onClick={toggle}>Toggle</button>
</aside>
);
}
Carrito de tienda con persistencia
// src/lib/cart.ts
import { create } from 'zustand';
import { persist, createJSONStorage, devtools } from 'zustand/middleware';
import { immer } from 'zustand/middleware/immer';
interface CartItem {
id: string;
productId: string;
name: string;
price: number;
quantity: number;
licenseType: 'one-time' | 'subscription';
}
interface CartState {
items: CartItem[];
couponCode: string | null;
couponDiscount: number;
// Computed (derived state — use selectors, not stored values)
// subtotal, total, itemCount — computed in selectors
// Actions
addItem: (item: Omit<CartItem, 'quantity'>) => void;
removeItem: (productId: string) => void;
updateQuantity: (productId: string, quantity: number) => void;
applyCoupon: (code: string, discount: number) => void;
removeCoupon: () => void;
clearCart: () => void;
}
export const useCart = create<CartState>()(
devtools(
persist(
immer((set) => ({
items: [],
couponCode: null,
couponDiscount: 0,
addItem: (newItem) =>
set((state) => {
const existing = state.items.find((i) => i.productId === newItem.productId);
if (existing) {
existing.quantity += 1; // Immer allows direct mutation
} else {
state.items.push({ ...newItem, quantity: 1 });
}
}),
removeItem: (productId) =>
set((state) => {
state.items = state.items.filter((i) => i.productId !== productId);
}),
updateQuantity: (productId, quantity) =>
set((state) => {
if (quantity <= 0) {
state.items = state.items.filter((i) => i.productId !== productId);
} else {
const item = state.items.find((i) => i.productId === productId);
if (item) item.quantity = quantity;
}
}),
applyCoupon: (code, discount) =>
set((state) => {
state.couponCode = code;
state.couponDiscount = discount;
}),
removeCoupon: () =>
set((state) => {
state.couponCode = null;
state.couponDiscount = 0;
}),
clearCart: () =>
set((state) => {
state.items = [];
state.couponCode = null;
state.couponDiscount = 0;
}),
})),
{
name: 'ecosire-cart',
storage: createJSONStorage(() => localStorage),
partialize: (state) => ({
// Only persist items and coupon, not derived state
items: state.items,
couponCode: state.couponCode,
couponDiscount: state.couponDiscount,
}),
}
),
{ name: 'cart-store' }
)
);
// Selectors — computed from state, not stored
export const selectSubtotal = (state: CartState) =>
state.items.reduce((sum, item) => sum + item.price * item.quantity, 0);
export const selectTotal = (state: CartState) => {
const subtotal = selectSubtotal(state);
return subtotal * (1 - state.couponDiscount);
};
export const selectItemCount = (state: CartState) =>
state.items.reduce((sum, item) => sum + item.quantity, 0);
Patrón de corte para grandes tiendas
Para tiendas complejas, divídalas en porciones y componga:
// src/lib/stores/slices/filters.slice.ts
import type { StateCreator } from 'zustand';
export interface FiltersSlice {
search: string;
status: string;
page: number;
sortField: string;
sortDirection: 'asc' | 'desc';
setSearch: (search: string) => void;
setStatus: (status: string) => void;
setPage: (page: number) => void;
setSort: (field: string, direction: 'asc' | 'desc') => void;
resetFilters: () => void;
}
const initialFilters = {
search: '',
status: 'all',
page: 1,
sortField: 'createdAt',
sortDirection: 'desc' as const,
};
export const createFiltersSlice: StateCreator<FiltersSlice> = (set) => ({
...initialFilters,
setSearch: (search) => set({ search, page: 1 }), // Reset page on search
setStatus: (status) => set({ status, page: 1 }),
setPage: (page) => set({ page }),
setSort: (field, direction) => set({ sortField: field, sortDirection: direction }),
resetFilters: () => set(initialFilters),
});
// src/lib/stores/slices/selection.slice.ts
import type { StateCreator } from 'zustand';
export interface SelectionSlice {
selectedIds: Set<string>;
selectAll: boolean;
toggleSelection: (id: string) => void;
selectAllItems: (ids: string[]) => void;
clearSelection: () => void;
}
export const createSelectionSlice: StateCreator<SelectionSlice> = (set) => ({
selectedIds: new Set(),
selectAll: false,
toggleSelection: (id) =>
set((state) => {
const next = new Set(state.selectedIds);
if (next.has(id)) {
next.delete(id);
} else {
next.add(id);
}
return { selectedIds: next, selectAll: false };
}),
selectAllItems: (ids) =>
set({ selectedIds: new Set(ids), selectAll: true }),
clearSelection: () =>
set({ selectedIds: new Set(), selectAll: false }),
});
// src/lib/stores/contacts-table.store.ts
import { create } from 'zustand';
import { devtools } from 'zustand/middleware';
import { createFiltersSlice, type FiltersSlice } from './slices/filters.slice';
import { createSelectionSlice, type SelectionSlice } from './slices/selection.slice';
type ContactsTableStore = FiltersSlice & SelectionSlice;
export const useContactsTableStore = create<ContactsTableStore>()(
devtools(
(...args) => ({
...createFiltersSlice(...args),
...createSelectionSlice(...args),
}),
{ name: 'contacts-table-store' }
)
);
Prevención de re-renderizaciones innecesarias
Zustand vuelve a renderizar el componente cuando cambia el valor seleccionado (por referencia para objetos).
// PROBLEM: new object created on every render → infinite re-renders
const { search, page } = useContactsTableStore((state) => ({
search: state.search,
page: state.page,
}));
// SOLUTION 1: Select primitives individually
const search = useContactsTableStore((state) => state.search);
const page = useContactsTableStore((state) => state.page);
// SOLUTION 2: Use useShallow for object selections
import { useShallow } from 'zustand/react/shallow';
const { search, page } = useContactsTableStore(
useShallow((state) => ({ search: state.search, page: state.page }))
);
// SOLUTION 3: Select an action (actions never change reference)
const setSearch = useContactsTableStore((state) => state.setSearch);
Consulta Zustand + TanStack: borrar separación
La disciplina clave: Zustand para el estado del cliente, TanStack Query para el estado del servidor, nunca se superpongan.
// WRONG: storing server data in Zustand
const useContactsStore = create(() => ({
contacts: [], // Server data in Zustand — invalidation nightmare
fetchContacts: async () => { /* fetch and set */ },
}));
// CORRECT: TanStack Query for server data, Zustand for UI state
// TanStack Query
const { data: contacts } = useContacts({ page, limit, search });
// Zustand — only UI-specific state
const { search, page, setSearch, setPage } = useContactsTableStore();
La clave de consulta reacciona a los cambios de estado de Zustand, por lo que filtrar/ordenar simplemente funciona:
function ContactsPage() {
// UI state from Zustand
const search = useContactsTableStore((s) => s.search);
const page = useContactsTableStore((s) => s.page);
const status = useContactsTableStore((s) => s.status);
// Server state from TanStack Query, driven by Zustand state
const { data, isLoading } = useContacts({ search, page, status, limit: 20 });
return <ContactsTable data={data?.data ?? []} loading={isLoading} />;
}
Tienda de formularios de varios pasos
// src/lib/stores/onboarding.store.ts
import { create } from 'zustand';
import { persist, createJSONStorage } from 'zustand/middleware';
interface OnboardingData {
company: { name: string; size: string; industry: string };
contact: { name: string; email: string; phone: string };
requirements: { erp: string; modules: string[]; budget: string };
}
interface OnboardingStore {
currentStep: number;
completed: Set<number>;
data: Partial<OnboardingData>;
setStep: (step: number) => void;
updateStepData: <K extends keyof OnboardingData>(
step: K,
data: OnboardingData[K]
) => void;
markStepComplete: (step: number) => void;
reset: () => void;
}
export const useOnboardingStore = create<OnboardingStore>()(
persist(
(set) => ({
currentStep: 0,
completed: new Set(),
data: {},
setStep: (step) => set({ currentStep: step }),
updateStepData: (key, stepData) =>
set((state) => ({
data: { ...state.data, [key]: stepData },
})),
markStepComplete: (step) =>
set((state) => ({
completed: new Set([...state.completed, step]),
})),
reset: () => set({ currentStep: 0, completed: new Set(), data: {} }),
}),
{
name: 'onboarding-progress',
storage: createJSONStorage(() => sessionStorage),
// Serialize Set properly
partialize: (state) => ({
...state,
completed: Array.from(state.completed),
}),
merge: (persisted: any, current) => ({
...current,
...persisted,
completed: new Set(persisted.completed ?? []),
}),
}
)
);
Probando las tiendas Zustand
// src/lib/stores/__tests__/cart.store.spec.ts
import { describe, it, expect, beforeEach } from 'vitest';
import { useCart, selectSubtotal, selectTotal } from '../cart';
describe('Cart Store', () => {
beforeEach(() => {
// Reset store state between tests
useCart.setState({
items: [],
couponCode: null,
couponDiscount: 0,
});
});
it('adds items to the cart', () => {
const { addItem } = useCart.getState();
addItem({ id: '1', productId: 'prod_1', name: 'Odoo Module', price: 249 });
const { items } = useCart.getState();
expect(items).toHaveLength(1);
expect(items[0].quantity).toBe(1);
});
it('increments quantity when same product added again', () => {
const { addItem } = useCart.getState();
addItem({ id: '1', productId: 'prod_1', name: 'Odoo Module', price: 249 });
addItem({ id: '1', productId: 'prod_1', name: 'Odoo Module', price: 249 });
const { items } = useCart.getState();
expect(items).toHaveLength(1);
expect(items[0].quantity).toBe(2);
});
it('calculates subtotal correctly', () => {
useCart.setState({
items: [
{ id: '1', productId: 'p1', name: 'A', price: 100, quantity: 2, licenseType: 'one-time' },
{ id: '2', productId: 'p2', name: 'B', price: 50, quantity: 1, licenseType: 'one-time' },
],
});
expect(selectSubtotal(useCart.getState())).toBe(250);
});
it('applies coupon discount', () => {
useCart.setState({
items: [{ id: '1', productId: 'p1', name: 'A', price: 100, quantity: 1, licenseType: 'one-time' }],
couponCode: 'SAVE20',
couponDiscount: 0.2,
});
expect(selectTotal(useCart.getState())).toBe(80);
});
});
Preguntas frecuentes
¿Aún necesito Context API con Zustand?
Casi nunca. El singleton a nivel de módulo de Zustand reemplaza la mayoría de los casos de uso de Context API. El principal caso de uso restante de Context es la inyección de dependencia: pasar una instancia de tienda específica a un subárbol (útil para pruebas o cuando necesita varias instancias de tienda independientes). Para eso, Zustand proporciona createStore() + useStore() que funcionan con un contexto de React para la instancia de la tienda.
¿Cómo se compara Zustand con Redux Toolkit?
Redux Toolkit tiene más estructura (porciones, reductores, acciones) y una mejor integración de DevTools para la depuración compleja de viajes en el tiempo. Zustand tiene menos texto estándar, un paquete más pequeño (2,9 KB frente a ~30 KB para Redux + RTK) y no requiere un proveedor. Para la mayoría de aplicaciones, Zustand es más sencillo y suficiente. Elija Redux Toolkit si tiene un equipo grande que se beneficia de patrones aplicados o necesita funciones avanzadas de DevTools.
¿Cómo uso Zustand con Next.js App Router SSR?
Las tiendas Zustand son singletons a nivel de módulo: seguras para los componentes del cliente, pero no se pueden usar en los componentes del servidor (sin API de navegador, sin ventana). Inicialice las tiendas en los componentes 'use client' únicamente. Para la hidratación SSR de los datos iniciales, utilice HydrationBoundary de TanStack Query para los datos del servidor. Para el estado de solo cliente (carrito, preferencias de UI) que debe persistir durante la navegación, use el middleware persist con localStorage.
¿Qué es el middleware immer y cuándo debo usarlo?
El middleware immer envuelve la función set de Zustand con Immer, lo que le permite escribir código mutante en acciones (state.items.push(item)) que en realidad es inmutable bajo el capó. Úselo cuando tenga actualizaciones de estado anidadas que sean incómodas con la sintaxis extendida, como actualizar una propiedad profundamente anidada o trabajar con matrices. Agrega ~6 KB a su paquete; vale la pena para tiendas complejas, pero innecesario para las simples.
¿Cómo evito cierres obsoletos en acciones de Zustand?
Zustand pasa el estado actual a la devolución de llamada set, por lo que siempre use la forma funcional al leer el estado dentro de una acción: set((state) => ({ count: state.count + 1 })) en lugar de capturar state.count del cierre. Para acciones asíncronas que leen el estado después de un await, llame a getState() en el punto de uso en lugar de capturar el estado en el cierre antes de la espera.
Próximos pasos
El tamaño mínimo de Zustand y su patrón de corte componible lo convierten en la herramienta adecuada para el estado del cliente en aplicaciones React de cualquier tamaño. Junto con TanStack Query para el estado del servidor, tiene una arquitectura de administración de estado limpia y escalable sin sobrecargas repetitivas.
ECOSIRE crea aplicaciones React con Zustand + TanStack Query como pila de gestión de estado estándar, que presta servicio a paneles de administración complejos, portales de clientes y flujos de comercio electrónico. Explore nuestros servicios de ingeniería frontend para aprender cómo diseñamos aplicaciones React escalables.
Escrito por
ECOSIRE Research and Development Team
Construyendo productos digitales de nivel empresarial en ECOSIRE. Compartiendo perspectivas sobre integraciones Odoo, automatización de eCommerce y soluciones empresariales impulsadas por IA.
Artículos relacionados
NestJS 11 Enterprise API Patterns
Master NestJS 11 enterprise patterns: guards, interceptors, pipes, multi-tenancy, and production-ready API design for scalable backend systems.
Next.js 16 App Router: Production Patterns and Pitfalls
Production-ready Next.js 16 App Router patterns: server components, caching strategies, metadata API, error boundaries, and performance pitfalls to avoid.
API Integration Patterns for OpenClaw Agents
Technical patterns for integrating OpenClaw AI agents with REST APIs, GraphQL, webhooks, and enterprise systems. Covers authentication, error handling, rate limiting, and testing.