Storybook

Storybook es una herramienta sumamente valiosa en el desarrollo de aplicaciones, ya que permite la visualización y exploración de componentes de forma aislada, lo que significa que puedes ver y probar un componente específico sin tener que ejecutar toda la aplicación. Esto resulta extremadamente útil durante el proceso de desarrollo, ya que te permite concentrarte en la construcción y refinamiento de componentes individuales de manera eficiente, sin la necesidad de navegar por la aplicación en su totalidad.

Además de su capacidad para facilitar el desarrollo y la depuración de componentes, Storybook es también una herramienta clave para la creación de un "design system" o sistema de diseño. Un "design system" es un conjunto cohesivo de principios de diseño, componentes reutilizables y directrices de estilo que garantizan la coherencia visual y de interacción en toda la aplicación. Storybook es un lugar ideal para compilar y documentar estos componentes y sus variaciones, lo que permite a los diseñadores y desarrolladores colaborar de manera efectiva para definir y mantener un diseño consistente en toda la aplicación. En resumen, Storybook no solo simplifica el proceso de desarrollo y pruebas, sino que también sirve como una herramienta fundamental en la creación y gestión de un sistema de diseño sólido y coherente.

Sin embargo, no suele ser sencillo de configurar. Aunque la herramienta de instalación que proporciona suele reconocer el framework, normalmente no es capaz de reconocer los temas que utilizamos o ciertas configuraciones de typescript como las rutas.

Instalación

En vez de dirigirnos a la web principal, vamos a indicar los pasos a seguir. Lo primero es instalar storybook dentro de nuestro proyecto. Seleccionaremos la configuración mínima.

npm create storybook@latest

Info

La primera vez que se instala se inicia solo.

Se nos abrirá esta página con algunos componentes de ejemplo:

Para tener soporte de tema oscuro, necesitamos también instalar el siguiente paquete.

Warning

Para instalar el nuevo plugin, cierra el servicio de storybook que tienes abierto con Ctrl+C, y cuando termines de configurarlo puedes volver a ejecutar storybook con esta orden:

npm run storybook

Creación de una historia

Una historia en Storybook es una representación visual y funcional de un componente de React en un estado particular o variación. Cada historia describe cómo se ve y se comporta un componente en un contexto específico, lo que facilita la visualización y documentación de su uso y apariencia.

Vamos a crear la historia del componente que creamos antes:

src/stories/components/theme-switcher.stories.ts

import { Meta, StoryObj } from '@storybook/react'

import { ThemeSwitcher } from '@/components/theme-switcher/theme-switcher'

const meta = {
  component: ThemeSwitcher,
  parameters: {
    layout: 'centered',
  },
  tags: ['autodocs'],
  title: 'Components/ThemeSwitcher',
} satisfies Meta<typeof ThemeSwitcher>

export default meta
type Story = StoryObj<typeof meta>

export const Basic: Story = {}

Y aparecerá una nueva sección llamada componentes que tendrá nuestra historia. Si accedemos a ella veremos que el componente no se ve correctamente.

Configuración de Storybook

Storybook es una aplicación distinta a la de next, por tanto, no tiene por qué cargar la misma configuración que tenemos en nuestro proyecto. Esta es la parte más complicada de hacer funcionar Storybook.

En nuestro caso tenemos dos partes que tenemos que configurar: los estilos de HeroUI y los providers para los estados de los componentes.

Primero vamos a cargar los providers a la hora de visualizar los componentes:

.storybook/preview.ts

import '@/app/globals.css'

import { withThemeByClassName } from '@storybook/addon-themes'
import type { Preview } from '@storybook/react'

const preview: Preview = {
  decorators: [
    withThemeByClassName({
      themes: {
        light: 'light',
        dark: 'dark',
      },
      defaultTheme: 'light',
    }),
  ],
  parameters: {
    controls: {
      matchers: {
        color: /(background|color)$/i,
        date: /Date$/i,
      },
    },
  },
}

export default preview

Ahora veremos nuestra historia de forma correcta. Podemos ya incluso borrar los componentes de ejemplo.

Ejercicio

Guarda los cambios que hemos hecho y la historia que hemos creado en git. Storybook crea una serie de historias de ejemplo en el directorio src/stories. Recuerda no guardarlas en git. Solo guarda lo que pertenece a nuestro proyecto.