Por qué aislar la interfaz antes de integrarla
Cuando una aplicación React crece, los componentes visuales empiezan a depender de rutas, datos remotos, sesiones de usuario y estados globales. Para ver cómo luce una alerta de error hay que provocar el error real, y para revisar una tarjeta sin imagen hay que encontrar un registro de base de datos que no tenga imagen. Ese roce constante hace que los estados raros se prueben poco y que los defectos visuales lleguen a producción.
Storybook resuelve este problema ofreciendo un taller aparte de la aplicación. Cada componente se renderiza solo, con las props que tú decidas, y cada combinación interesante se guarda como una story, es decir, un ejemplo ejecutable y navegable. El resultado es un catálogo vivo que sirve a la vez como entorno de desarrollo, documentación, banco de pruebas visual y punto de revisión para diseño y producto.
En este tutorial construiremos desde cero una pequeña biblioteca con tres piezas propias: Badge, Alert y Card. Usaremos la versión actual de Storybook sobre un proyecto React con Vite, y recorreremos la configuración moderna: historias en formato CSF3, la alternativa con CSF Factories, documentación automática, controles interactivos, el addon de accesibilidad y el addon de pruebas basado en Vitest. Al final verás errores frecuentes y criterios para mantener el catálogo ordenado a largo plazo.
Si todavía no dominas los fundamentos de React, conviene repasar antes la guía completa de React para principiantes, porque aquí se da por sentado que sabes escribir componentes funcionales y manejar props.
Versiones que usaremos y requisitos previos
Antes de escribir código conviene fijar el terreno, porque Storybook ha cambiado bastante en las últimas versiones mayores. Según las comprobaciones hechas al preparar este artículo, la línea estable vigente de Storybook es la 10, y las notas de versión más recientes que se localizaron corresponden a la 10.6, publicada en septiembre de 2026. En React, la última versión menor estable es la 19.3, anunciada en septiembre de 2026. En Vite, la línea estable es la 8.1, anunciada en junio de 2026. No fijamos números de parche porque cambian cada pocas semanas; para saber cuál instalará tu equipo, consulta el registro de npm con npm view storybook version.
Estos son los requisitos prácticos:
- Una versión de Node.js compatible con Vite 8 y Storybook 10. Ambos exigen una versión moderna y han dejado atrás las antiguas, así que usa una LTS reciente.
- Un gestor de paquetes: npm, pnpm o yarn. Los ejemplos usan npm.
- Conocimientos básicos de TypeScript. Storybook funciona igual con JavaScript, pero el tipado aporta mucho en los controles.
Hay varios cambios importantes respecto a tutoriales antiguos que seguramente encuentres por la red. Create React App está abandonado y ya no es el punto de partida recomendado; hoy se usa Vite. El paquete @storybook/addon-essentials y el montón de addons sueltos de la era 6 y 7 se fueron integrando en el núcleo, de modo que las acciones, los controles, el visor de tamaños y los fondos vienen incluidos sin instalar nada. Storybook 10 distribuye sus paquetes solo como módulos ESM, lo que obliga a que tu configuración también lo sea. Y los addons de historias de código fuente y de snapshots con Jest que se recomendaban antes han sido sustituidos por la pestaña de código de la documentación y por el addon de Vitest.
Crear el proyecto con Vite y arrancar Storybook
Empezamos generando una aplicación React con TypeScript. El nombre panel-ui es solo un ejemplo.
npm create vite@latest panel-ui -- --template react-ts
cd panel-ui
npm install
Ahora inicializamos Storybook dentro del proyecto. El asistente detecta que usas React y Vite, instala el framework correspondiente y deja la configuración lista.
npm create storybook@latest
Durante la ejecución, el asistente te pregunta qué funciones quieres activar. En las versiones recientes ofrece, entre otras, la documentación, las pruebas y la accesibilidad. Para seguir este tutorial acepta las tres. Si el proyecto ya tenía Storybook de una versión anterior, el comando de migración es distinto y conviene ejecutar npx storybook@latest upgrade, que aplica además las transformaciones automáticas de configuración.
Cuando termina, aparecen nuevos scripts en package.json. Los dos que más usarás son estos:
{
"scripts": {
"storybook": "storybook dev -p 6006",
"build-storybook": "storybook build"
}
}
Para levantar el entorno de desarrollo ejecuta el primero. Se abrirá el navegador en el puerto 6006 con una barra lateral que contiene historias de ejemplo.
npm run storybook
storybook v10.x
Storybook ready!
Local: http://localhost:6006/
La salida concreta cambia con la versión instalada, pero lo importante es que el servidor de desarrollo reutiliza el compilador de Vite, así que los cambios en componentes se reflejan casi al instante gracias a la recarga en caliente.
Qué contiene la carpeta de configuración
El asistente crea una carpeta oculta llamada .storybook y una carpeta src/stories con ejemplos. Echemos un vistazo a la estructura resultante.
panel-ui/
├── .storybook/
│ ├── main.ts
│ ├── preview.ts
│ └── vitest.setup.ts
├── src/
│ ├── stories/
│ ├── components/
│ └── main.tsx
├── vite.config.ts
└── package.json
El archivo main.ts decide qué historias se cargan, qué addons están activos y qué framework se usa. Un contenido típico es este:
import type { StorybookConfig } from '@storybook/react-vite';
const config: StorybookConfig = {
stories: ['../src/**/*.mdx', '../src/**/*.stories.@(ts|tsx)'],
addons: [
'@storybook/addon-docs',
'@storybook/addon-a11y',
'@storybook/addon-vitest',
],
framework: '@storybook/react-vite',
};
export default config;
El patrón de stories indica que cualquier archivo con la terminación .stories.tsx dentro de src se considera un catálogo de ejemplos. Esto permite colocar cada archivo de historias al lado de su componente, algo que facilita mucho el mantenimiento. El archivo preview.ts define opciones globales aplicadas a todas las historias, como controles por defecto, fondos o decoradores. El archivo vitest.setup.ts se genera cuando activas el addon de pruebas y lo veremos más adelante.
Un detalle útil: Storybook reutiliza tu vite.config.ts. Si ya tienes alias de rutas o plugins, se aplican también al catálogo. Así evitas mantener dos configuraciones divergentes.
Primer componente: la etiqueta Badge
Para no mezclar el código de la biblioteca con los ejemplos que trae el asistente, crearemos una carpeta por componente. Un componente de etiqueta es un buen primer candidato porque es pequeño y tiene variantes claras.
src/components/
├── Badge/
│ ├── Badge.tsx
│ ├── Badge.css
│ └── Badge.stories.tsx
├── Alert/
└── Card/
Este es el componente. Define tres tonos y dos tamaños, y acepta cualquier contenido como hijo.
import type { ReactNode } from 'react';
import './Badge.css';
export type BadgeTone = 'neutral' | 'success' | 'warning' | 'danger';
export interface BadgeProps {
/** Color semántico de la etiqueta. */
tone?: BadgeTone;
/** Tamaño visual. */
size?: 'sm' | 'md';
/** Muestra un punto indicador antes del texto. */
withDot?: boolean;
children: ReactNode;
}
export function Badge({
tone = 'neutral',
size = 'md',
withDot = false,
children,
}: BadgeProps) {
const className = ['badge', `badge--${tone}`, `badge--${size}`].join(' ');
return (
<span className={className}>
{withDot && <span className="badge__dot" aria-hidden="true" />}
{children}
</span>
);
}
Observa que los comentarios de documentación sobre cada prop no son decorativos. Storybook los lee mediante análisis estático del tipo y los muestra como descripciones en la tabla de controles y en la página de documentación. Escribirlos una vez te da documentación gratis.
Los estilos son sencillos y usan variables CSS para que luego puedas cambiar el tema desde un único lugar:
.badge {
display: inline-flex;
align-items: center;
gap: 0.375rem;
border-radius: 999px;
font-weight: 600;
line-height: 1;
}
.badge--md { padding: 0.375rem 0.75rem; font-size: 0.875rem; }
.badge--sm { padding: 0.25rem 0.5rem; font-size: 0.75rem; }
.badge--neutral { background: #e5e7eb; color: #1f2937; }
.badge--success { background: #d1fae5; color: #065f46; }
.badge--warning { background: #fef3c7; color: #78350f; }
.badge--danger { background: #fee2e2; color: #7f1d1d; }
.badge__dot {
width: 0.5rem;
height: 0.5rem;
border-radius: 50%;
background: currentColor;
}
Escribir historias con el formato CSF3
El formato estándar para describir historias se llama Component Story Format, y su tercera versión, CSF3, es la base sobre la que trabaja todo lo demás. Un archivo exporta por defecto un objeto de metadatos que describe el componente, y cada exportación con nombre es una historia. No hace falta escribir funciones de render: basta con un objeto con las props.
import type { Meta, StoryObj } from '@storybook/react-vite';
import { Badge } from './Badge';
const meta = {
title: 'Biblioteca/Badge',
component: Badge,
tags: ['autodocs'],
args: {
children: 'Pendiente',
},
} satisfies Meta<typeof Badge>;
export default meta;
type Story = StoryObj<typeof meta>;
export const Neutral: Story = {};
export const Exito: Story = {
args: { tone: 'success', children: 'Pagado' },
};
export const Advertencia: Story = {
args: { tone: 'warning', children: 'Revisión', withDot: true },
};
export const Peligro: Story = {
args: { tone: 'danger', children: 'Rechazado', withDot: true },
};
Fíjate en varias decisiones. El operador satisfies mantiene el tipo concreto del objeto de metadatos y, a la vez, valida que sea compatible con Meta; gracias a eso StoryObj<typeof meta> sabe qué props ya vienen definidas globalmente y no te obliga a repetirlas en cada historia. Los argumentos del nivel de metadatos actúan como valores base y cada historia solo sobrescribe lo que cambia. Y la importación de tipos proviene del paquete del framework, no del paquete de React genérico, algo que cambió en versiones recientes y que provoca errores de tipos si copias código antiguo.
Una buena regla para decidir qué historias escribir es que cada una responda a una pregunta concreta de diseño o de negocio: qué aspecto tiene con texto largo, qué ocurre sin icono, cómo se ve en estado desactivado. Una historia que solo repite la anterior con un color distinto aporta poco. Esta mentalidad de construir interfaces pieza a pieza se conoce como desarrollo dirigido por componentes aislados y, bien aplicada, hace que los estados límite se diseñen a propósito en lugar de descubrirse en producción.
Controles interactivos y argTypes
Al abrir la historia verás debajo del lienzo un panel de controles. Storybook infiere automáticamente el tipo de control a partir de los tipos de TypeScript: una unión de cadenas se convierte en un selector de opciones, un booleano en un interruptor, un texto en un campo editable. Esto te permite experimentar con el componente sin tocar el código, y cualquier persona del equipo, incluso sin conocimientos técnicos, puede probar combinaciones.
A veces la inferencia no basta. Con argTypes puedes afinar la presentación de cada control, añadir descripciones, agrupar categorías o ocultar props que no deban editarse:
const meta = {
title: 'Biblioteca/Badge',
component: Badge,
tags: ['autodocs'],
args: { children: 'Pendiente' },
argTypes: {
tone: {
control: 'radio',
options: ['neutral', 'success', 'warning', 'danger'],
description: 'Tono semántico que comunica el estado.',
},
size: {
control: 'inline-radio',
table: { category: 'Apariencia' },
},
children: {
control: 'text',
table: { disable: false },
},
},
} satisfies Meta<typeof Badge>;
Los controles escriben sus valores en la dirección del navegador, de modo que puedes copiar el enlace de una historia con una configuración exacta y compartirlo en una revisión de código. Es una forma excelente de reportar un defecto visual: se envía el enlace y quien lo recibe ve el mismo estado sin explicaciones.
Alert: estados, acciones y pruebas de interacción
El segundo componente es más interesante porque tiene comportamiento. Una alerta puede cerrarse y avisa a quien la use mediante un callback.
import { useState, type ReactNode } from 'react';
import './Alert.css';
export interface AlertProps {
variant?: 'info' | 'success' | 'error';
title: string;
children?: ReactNode;
/** Se llama cuando la persona usuaria cierra el aviso. */
onDismiss?: () => void;
}
export function Alert({ variant = 'info', title, children, onDismiss }: AlertProps) {
const [visible, setVisible] = useState(true);
if (!visible) return null;
const role = variant === 'error' ? 'alert' : 'status';
return (
<div className={`alert alert--${variant}`} role={role}>
<div className="alert__body">
<strong className="alert__title">{title}</strong>
{children && <p className="alert__text">{children}</p>}
</div>
{onDismiss && (
<button
type="button"
className="alert__close"
aria-label="Cerrar aviso"
onClick={() => {
setVisible(false);
onDismiss();
}}
>
x
</button>
)}
</div>
);
}
Para verlo funcionar necesitamos una función espía que registre las llamadas. En las versiones actuales todo lo relacionado con pruebas se importa desde el subpaquete storybook/test, que reúne fn, expect y utilidades de Testing Library. Además, la función play recibe en su contexto el objeto canvas para consultar el DOM y userEvent para simular acciones.
import type { Meta, StoryObj } from '@storybook/react-vite';
import { expect, fn } from 'storybook/test';
import { Alert } from './Alert';
const meta = {
title: 'Biblioteca/Alert',
component: Alert,
tags: ['autodocs'],
args: {
title: 'Cambios guardados',
children: 'Tu perfil se actualizó correctamente.',
onDismiss: fn(),
},
} satisfies Meta<typeof Alert>;
export default meta;
type Story = StoryObj<typeof meta>;
export const Informativa: Story = {};
export const ConError: Story = {
args: {
variant: 'error',
title: 'No se pudo guardar',
children: 'Comprueba tu conexión e inténtalo de nuevo.',
},
};
export const SeCierraAlPulsar: Story = {
play: async ({ canvas, userEvent, args }) => {
await userEvent.click(canvas.getByRole('button', { name: 'Cerrar aviso' }));
await expect(args.onDismiss).toHaveBeenCalledTimes(1);
await expect(canvas.queryByRole('status')).not.toBeInTheDocument();
},
};
El valor fn() crea un espía que además aparece registrado en el panel de acciones: cada vez que se invoca el callback verás una entrada con sus argumentos. La historia SeCierraAlPulsar es una prueba de interacción: Storybook ejecuta la función play después de renderizar y muestra cada paso en un panel con avance y retroceso. Si una aserción falla, la historia se marca en rojo en la barra lateral.
Este enfoque tiene mucho en común con las pruebas que ya conoces. Si quieres profundizar en cómo consultar roles y simular usuarios, el artículo sobre pruebas unitarias en React con Testing Library explica los mismos principios, que aquí se reutilizan casi sin cambios.
Card: composición, decoradores y contexto
El tercer componente combina otros dos y demuestra cómo documentar piezas compuestas. La tarjeta muestra un título, una descripción, una etiqueta de estado y un pie con acciones opcional.
import type { ReactNode } from 'react';
import { Badge, type BadgeProps } from '../Badge/Badge';
import './Card.css';
export interface CardProps {
title: string;
description: string;
status?: { label: string; tone: BadgeProps['tone'] };
footer?: ReactNode;
}
export function Card({ title, description, status, footer }: CardProps) {
return (
<article className="card">
<header className="card__header">
<h3 className="card__title">{title}</h3>
{status && <Badge tone={status.tone} size="sm">{status.label}</Badge>}
</header>
<p className="card__description">{description}</p>
{footer && <footer className="card__footer">{footer}</footer>}
</article>
);
}
Sus historias introducen un decorador. Un decorador es una función que envuelve la historia para darle un contexto que el componente necesita, por ejemplo un contenedor con ancho fijo, un proveedor de tema o un enrutador. Aquí limitamos el ancho para que la tarjeta no se estire a toda la pantalla.
import type { Meta, StoryObj } from '@storybook/react-vite';
import { Card } from './Card';
const meta = {
title: 'Biblioteca/Card',
component: Card,
tags: ['autodocs'],
decorators: [
(Story) => (
<div style={{ maxWidth: 360, margin: '1rem auto' }}>
<Story />
</div>
),
],
args: {
title: 'Informe trimestral',
description: 'Resumen de métricas de uso y de rendimiento del último trimestre.',
},
} satisfies Meta<typeof Card>;
export default meta;
type Story = StoryObj<typeof meta>;
export const Basica: Story = {};
export const ConEstado: Story = {
args: { status: { label: 'Publicado', tone: 'success' } },
};
export const ConPie: Story = {
args: {
status: { label: 'Borrador', tone: 'warning' },
footer: <button type="button">Editar</button>,
},
};
export const TextoMuyLargo: Story = {
args: {
title: 'Un título excepcionalmente largo que debería ocupar varias líneas sin romper el diseño',
description: 'Lorem ipsum '.repeat(30),
},
};
La historia TextoMuyLargo ilustra una práctica valiosa: usar el catálogo para forzar casos extremos. Es mucho más barato descubrir un desbordamiento aquí que en una pantalla real con datos de clientes.
Los decoradores también se pueden definir de forma global en preview.ts. Úsalos con moderación: un decorador global que añade un proveedor a todo cambia el comportamiento de cada historia, y si un componente depende de él sin que se note, será difícil aislarlo más tarde.
Documentación automática con autodocs
Seguramente has notado la línea tags: ['autodocs'] en los metadatos. Esa etiqueta le pide a Storybook que genere una página de documentación por componente, que aparece como entrada propia en la barra lateral. Incluye una descripción tomada del comentario de documentación del componente, la tabla de props con tipos y valores por defecto, y todas las historias renderizadas con su código fuente copiable.
La documentación depende del addon @storybook/addon-docs, que ya está en la lista de addons de main.ts. En las versiones anteriores formaba parte del paquete de utilidades esenciales; ahora se instala por separado, y si lo olvidas verás que la pestaña de documentación desaparece.
Si prefieres activar autodocs para todo el proyecto en lugar de repetir la etiqueta, puedes hacerlo una sola vez en la vista previa:
import type { Preview } from '@storybook/react-vite';
const preview: Preview = {
tags: ['autodocs'],
parameters: {
controls: {
matchers: {
color: /(background|color)$/i,
date: /Date$/i,
},
},
},
};
export default preview;
Con el bloque de matchers, cualquier prop cuyo nombre termine en color o background recibirá un selector de color, y las que terminen en Date un selector de fecha. Es un truco sencillo que ahorra definiciones repetidas.
Cuando la generación automática se queda corta, puedes escribir páginas MDX propias con guías de uso, normas de diseño o criterios de accesibilidad, y mezclar en ellas bloques que muestran historias reales. Así la documentación nunca se desactualiza respecto al código, porque lo que ve el lector es el propio componente.
CSF Factories: la sintaxis tipada del futuro
Además del CSF3 clásico, Storybook 10 incluye en estado de vista previa un formato nuevo llamado CSF Factories. Los responsables del proyecto han indicado que, al estar ya en preview, no esperan cambios importantes cuando se convierta en el formato por defecto en la próxima versión mayor. Su objetivo es resolver un problema real: en CSF3 los tipos se infieren de forma indirecta mediante Meta y StoryObj, y los addons no se reflejan en los tipos de las historias. Con factorías, la configuración global y los addons fluyen hasta cada historia con tipado completo.
El cambio empieza en la configuración, que pasa a usar funciones definidoras en lugar de objetos anotados con tipos:
// .storybook/preview.ts
import { definePreview } from '@storybook/react-vite';
import addonA11y from '@storybook/addon-a11y';
import addonDocs from '@storybook/addon-docs';
export default definePreview({
addons: [addonDocs(), addonA11y()],
tags: ['autodocs'],
});
Y así quedan las historias de la etiqueta con el nuevo formato. No hay ni Meta ni StoryObj: se crea el meta desde la vista previa y cada historia sale de él.
import preview from '../../../.storybook/preview';
import { Badge } from './Badge';
const meta = preview.meta({
title: 'Biblioteca/Badge',
component: Badge,
args: { children: 'Pendiente' },
});
export const Neutral = meta.story();
export const Exito = meta.story({
args: { tone: 'success', children: 'Pagado' },
});
La importación de la vista previa con una ruta relativa larga resulta incómoda, por lo que la documentación oficial recomienda definir un alias de importación en el proyecto, por ejemplo mediante el campo imports de package.json. Merece la pena configurarlo si adoptas el formato.
Hay que tener cuidado en dos puntos. Primero, no todos los addons admiten aún las anotaciones propias de factorías, así que comprueba la compatibilidad de los que uses. Segundo, si el archivo de preparación de Vitest pasa a usar factorías, todas las historias sometidas a pruebas deben usarlas también; mezclar ambos estilos exige mantener dos archivos de preparación. Para migrar de manera gradual existe un comando automático que convierte los archivos existentes:
npx storybook automigrate csf-factories
Mi recomendación práctica: para un proyecto nuevo y pequeño, puedes empezar directamente con factorías; para uno existente con cientos de historias, mantén CSF3, que sigue plenamente soportado, y migra por carpetas cuando haya un motivo claro.
Accesibilidad con el addon de Storybook
El addon @storybook/addon-a11y integra el motor axe en cada historia. Al abrir el panel de accesibilidad verás una lista de violaciones, de comprobaciones superadas y de elementos que requieren revisión manual, con el fragmento de DOM afectado resaltado en el lienzo. Como cada componente se examina en todos sus estados, detecta problemas que una auditoría de página completa no ve, por ejemplo el contraste insuficiente de la variante de advertencia.
Probemos con un caso. Si en la etiqueta eligiéramos un fondo claro con un texto gris suave, el panel avisaría de un contraste inferior al mínimo recomendado, y la corrección sería oscurecer el color del texto. Detectarlo aquí cuesta un minuto; encontrarlo después en una auditoría externa cuesta varios días de retrabajo.
El comportamiento del addon se controla con el parámetro a11y.test, que admite tres valores: error hace que las violaciones rompan las pruebas, todo las muestra como avisos sin fallar, y off desactiva la comprobación. Puedes fijar un valor global y sobrescribirlo por historia.
// .storybook/preview.ts
const preview = {
parameters: {
a11y: {
// Las violaciones hacen fallar las pruebas
test: 'error',
},
},
};
export default preview;
// Una historia con una deuda conocida que se corregirá más adelante
export const ColoresDeMarca: Story = {
parameters: {
a11y: { test: 'todo' },
},
};
El valor todo es una herramienta de gestión, no una excusa: permite adoptar la comprobación en un proyecto existente sin bloquear a todo el equipo desde el primer día y registrar la deuda de forma visible. Recuerda también que las herramientas automáticas detectan solo una parte de los problemas. Navegar con el teclado, probar un lector de pantalla y revisar el orden del foco siguen siendo tareas manuales. En esta línea, el atributo aria-hidden del punto decorativo de la etiqueta y el role dinámico de la alerta son decisiones que el addon no puede evaluar por ti.
Pruebas automáticas con el addon de Vitest
Hasta ahora has comprobado las historias abriendo el navegador. El addon @storybook/addon-vitest convierte esas mismas historias en pruebas automáticas ejecutables sin intervención. Cada historia se transforma en un caso de prueba: se renderiza en un navegador real, se ejecuta su función play y, si el addon de accesibilidad está configurado en modo estricto, se verifican también las violaciones.
Con el asistente, la integración suele quedar lista: se añade un proyecto de Vitest dedicado a Storybook en la configuración, y el archivo .storybook/vitest.setup.ts enlaza las anotaciones de la vista previa con el ejecutor. Un esquema de la configuración generada es el siguiente:
// vitest.config.ts (esquema)
import { defineConfig } from 'vitest/config';
import { storybookTest } from '@storybook/addon-vitest/vitest-plugin';
export default defineConfig({
test: {
projects: [
{
extends: true,
plugins: [storybookTest({ configDir: '.storybook' })],
test: {
name: 'storybook',
browser: {
enabled: true,
headless: true,
provider: 'playwright',
instances: [{ browser: 'chromium' }],
},
setupFiles: ['.storybook/vitest.setup.ts'],
},
},
],
},
});
El contenido exacto cambia según el proveedor de navegador que elijas y la versión de Vitest, por eso es mejor dejar que el asistente lo genere y luego revisarlo, en lugar de escribirlo a mano. Para ejecutar solo las pruebas de las historias usa el nombre del proyecto:
npx vitest --project=storybook
✓ |storybook| src/components/Badge/Badge.stories.tsx (4 tests)
✓ |storybook| src/components/Alert/Alert.stories.tsx (3 tests)
✓ |storybook| src/components/Card/Card.stories.tsx (4 tests)
Test Files 3 passed (3)
Tests 11 passed (11)
También puedes lanzar las pruebas desde la propia interfaz de Storybook mediante el widget de la barra lateral, que además muestra cobertura y resultados de accesibilidad por historia. Esto convierte el catálogo en una red de seguridad: cualquier cambio que rompa una interacción o introduzca una violación se detecta en el flujo normal de trabajo.
Una advertencia de alcance: las pruebas de historias son excelentes para comportamiento visible y accesibilidad por componente, pero no sustituyen a las pruebas unitarias de lógica pura ni a las de extremo a extremo. Considéralas una capa intermedia dentro de tu estrategia de pruebas.
Fondos, tamaños y temas globales
Un catálogo es más útil cuando permite ver los componentes en condiciones diferentes. Storybook incluye una barra de herramientas con selector de fondos, visor de tamaños de pantalla y rejilla de medidas. Todos se pueden configurar mediante parámetros, y los valores que definas aparecen como opciones:
const preview = {
parameters: {
backgrounds: {
options: {
claro: { name: 'Claro', value: '#ffffff' },
oscuro: { name: 'Oscuro', value: '#111827' },
},
},
viewport: {
options: {
movil: { name: 'Móvil', styles: { width: '390px', height: '844px' } },
tableta: { name: 'Tableta', styles: { width: '820px', height: '1180px' } },
},
},
},
initialGlobals: {
backgrounds: { value: 'claro' },
},
};
export default preview;
Para temas más completos, define un decorador global que lea un valor de la barra de herramientas y aplique una clase o atributo de tema al contenedor. Con ello compruebas modo claro y oscuro en cada componente sin duplicar historias. Si tu biblioteca usa variables CSS, como en nuestros estilos, basta con cambiar unas pocas definiciones en el contenedor.
Publicar el catálogo como sitio estático
Un catálogo solo en tu máquina no ayuda a nadie. Storybook genera un sitio estático que puedes alojar en cualquier servicio de archivos:
npm run build-storybook
La salida se escribe en la carpeta storybook-static. Es un conjunto de archivos HTML, JavaScript y recursos que no necesita servidor propio. Muchos equipos lo publican desde su sistema de integración continua en cada cambio a la rama principal, y además generan una vista previa por solicitud de cambio para que diseño y producto revisen sin instalar nada.
storybook-static/
├── index.html
├── iframe.html
├── assets/
└── project.json
Antes de publicar, ejecuta las pruebas de historias en el flujo de integración continua. Si el build del catálogo falla o una prueba de accesibilidad se rompe, el cambio no debería integrarse. De este modo el catálogo deja de ser un adorno y pasa a ser un requisito de calidad.
Errores frecuentes y cómo resolverlos
Estos son los tropiezos más comunes al montar un catálogo con la configuración actual.
- Las historias no aparecen en la barra lateral. Casi siempre el patrón de
storiesenmain.tsno coincide con la ubicación de los archivos. Comprueba la ruta relativa, que se calcula desde la carpeta.storybook, y revisa que la terminación sea exactamente.stories.tsx. - La pestaña de documentación no existe. Falta el addon de documentación en la lista de addons, o la etiqueta
autodocsno está en los metadatos ni en la vista previa. - Error por módulo CommonJS. Storybook 10 es solo ESM. Si tu
main.tsusarequireo tu proyecto declara un tipo de módulo incompatible, convierte las importaciones a la sintaxis estándar de módulos. - Los controles no muestran descripciones. El analizador necesita que las props estén declaradas con una interfaz o un tipo con nombre; las definiciones anónimas muy anidadas se infieren peor. Exporta el tipo de las props.
- Importaciones de pruebas que no se resuelven. Las versiones antiguas usaban paquetes sueltos con prefijo de organización para las utilidades de prueba. Ahora se importan desde
storybook/test. Actualiza los imports y elimina los paquetes obsoletos. - Estilos globales ausentes. El catálogo no carga el punto de entrada de tu aplicación. Importa la hoja de estilos global dentro de
preview.ts. - Componentes que dependen de contexto. Si un componente usa un enrutador o un proveedor de datos, falla al renderizar solo. Resuelve la dependencia con un decorador específico en lugar de globalizarlo.
- Pruebas de historias que fallan solo en integración continua. Suele faltar la instalación de los navegadores de Playwright en la máquina de CI; ejecuta el comando de instalación de navegadores antes de lanzar Vitest.
Cuando algo no funcione tras una actualización, usa la migración automática antes de editar a mano. La herramienta de actualización conoce los cambios entre versiones mayores y reescribe la configuración y los imports por ti.
Organizar el catálogo para que escale
Con tres componentes cualquier estructura funciona. Con sesenta, hace falta criterio. Algunas pautas que dan buen resultado:
- Colocar el archivo de historias junto al componente, no en una carpeta aparte. Las dos piezas cambian juntas y así los cambios aparecen en la misma revisión.
- Usar títulos jerárquicos separados por barras, como
Biblioteca/Formularios/Campo de texto, para que la barra lateral refleje la estructura de diseño y no la de carpetas. - Escribir una historia por estado relevante, y una historia de galería por componente con todas las variantes juntas para detectar incoherencias visuales de un vistazo.
- Dar nombres de historia que describan el estado, no la implementación:
SinConexiones mejor queConPropErrorTrue. - Tratar las props documentadas como parte del contrato público: si cambia su significado, se actualiza el comentario y la historia en la misma modificación.
Esta organización encaja con las ideas de modularidad que se aplican en proyectos grandes. Para decidir dónde vive cada componente y cómo separar piezas compartidas de piezas de dominio, te será útil el artículo sobre cómo estructurar proyectos React complejos, cuyas reglas de capas se trasladan sin esfuerzo a la jerarquía del catálogo.
Otro hábito rentable es revisar las historias en las solicitudes de cambio. Si alguien modifica el margen de la tarjeta, el cambio visual se ve en el catálogo desplegado y se discute con evidencia, sin necesidad de ejecutar nada localmente. También conviene definir una política de eliminación: una historia que ya no representa un caso real se borra, igual que un código muerto.
Comparación con otras opciones y cuándo no usarlo
Storybook no es la única forma de trabajar con componentes aislados, y tampoco siempre es la más adecuada. Si tienes una aplicación pequeña con diez componentes y un solo desarrollador, una página de pruebas dentro de la propia aplicación puede bastar. La inversión empieza a compensar cuando concurren varios de estos factores: varias personas tocan la interfaz, hay diseñadores que necesitan revisar, existe una biblioteca compartida entre aplicaciones, o la accesibilidad es un requisito formal.
Frente a las pruebas con Testing Library puramente en el terminal, Storybook añade visibilidad y revisión visual; frente a las herramientas de regresión visual en la nube, ofrece el entorno donde nacen las capturas, con el que se pueden combinar. Su coste real es mantenimiento: cada historia es código que hay que conservar, y un catálogo abandonado se vuelve peor que ninguno porque miente. Por eso conviene empezar pequeño, con los componentes más reutilizados, y crecer solo mientras alguien se haga responsable de mantenerlo.
Hay además un aspecto de rendimiento. El arranque del servidor de desarrollo depende de la cantidad de historias y de addons; si notas lentitud, filtra las historias por carpeta durante el desarrollo o evita importar módulos pesados en la configuración global. En el build final, el tamaño depende sobre todo de las dependencias que importen tus componentes.
Conclusiones
Montar Storybook con React y Vite hoy es mucho más sencillo que hace unos años: un solo comando crea la configuración, el servidor aprovecha el compilador de Vite y los addons que antes había que reunir a mano forman parte del núcleo o se activan con una pregunta del asistente. Con tres componentes sencillos, Badge, Alert y Card, hemos recorrido el ciclo completo: escribir historias en CSF3, afinar controles, documentar con autodocs, comprobar interacciones, vigilar la accesibilidad y automatizar todo con Vitest.
Recuerda las ideas clave. Una historia es un estado concreto del componente, no una demostración genérica. Los comentarios de tipos son la fuente de tu documentación. El addon de accesibilidad y el de pruebas convierten el catálogo en una barrera de calidad si los ejecutas en integración continua. Y CSF Factories es una evolución tipada que ya puedes probar, aunque CSF3 sigue siendo una elección sólida y totalmente soportada.
Como siguiente paso, elige tres componentes reales de tu proyecto, escribe sus historias con los casos extremos que más temes y activa las pruebas en tu flujo de integración. En pocos días notarás que las revisiones visuales son más rápidas y que los defectos se detectan antes de que lleguen a tus usuarios.
