Creando una documentación para aplicaciones FrontEnd

Esta es una republicación del post de blog de Vinnicius Gomes – Senior Frontend Engineer en Zappts.

En este post vamos a hablar sobre cómo crear una documentación para una aplicación FrontEnd de forma sencilla e intuitiva.

Si no te gustan los estándares antiguos de documentación como a mí, ¡tus problemas terminaron! 🤩

Hoy te voy a mostrar una herramienta que ha ganado mucho espacio en la comunidad y el mercado, que no es otra que Storybook, una herramienta Open Source que prepara un entorno de desarrollo para componentes de UI.

Vamos a lo que importa 🤓

Ah, antes de comenzar, voy a utilizar Storybook con React, pero soporta varios otros frameworks y libs como 👇

Sin más demoras, vamos al código:

Vamos a crear una aplicación React utilizando CRA, ejecutando el comando:

npx create-react-app my-app

Con el proyecto creado, vamos a instalar Storybook ejecutando el comando: npx sb init

Puedes acceder a la documentación para saber más sobre la instalación a través de este enlace.

Después de que la instalación se complete, se crearán dos carpetas en nuestro proyecto 👇

Una carpeta llamada .storybook y otra dentro de /src/stories, la carpeta .storybook contiene las configuraciones que no vamos a abordar hoy, pero puedes leer más sobre estas configuraciones en la documentación, y también se creó la carpeta /src/stories que es donde escribiremos nuestras historias.

Vamos a ejecutar Storybook

Ejecuta el comando npm run storybook y accede a http://localhost:6006 verás una pantalla como esta 👇

¡Esto significa que nuestro Storybook se instaló y está funcionando correctamente! 🤩

Ahora vamos a entender la interfaz de Storybook

En el lado izquierdo de la pantalla, tenemos la lista de stories. Storybook creó algunos componentes de ejemplo.

Haciendo clic en el componente de botón, veremos algo parecido a esto 👇

Donde se renderiza el componente, y en la parte inferior tenemos un menú con algunas opciones donde podemos interactuar con el componente y ver su funcionamiento.

En el menú superior tenemos una opción Docs, haciendo clic en ella se abrirá la documentación del componente 👇

Ahora vamos a crear una nueva Story

Para comenzar, limpié la carpeta stories dejando solo la introducción y los assets 👇

Vamos a crear un simple componente Alert, para eso crearemos 3 archivos 👇

Como el enfoque de este post no es crear un componente, saltaré esa parte, el código del componente está disponible en este repositorio.

Nuestro componente Alert quedó así 👇

Ahora vamos a crear la Story, para eso crea un archivo Alert.stories.js 👇

Tranquilo, sé que hay mucho contenido aquí, ¡pero te explicaré las partes importantes!

Líneas 6–16: Aquí estamos creando la configuración default de nuestra Story, definiendo un título, apuntando al componente y definiendo los args predeterminados. En la línea 10 estamos definiendo que el prop type se mostrará como un select en la pantalla de Storybook recibiendo un array de opciones:

Línea 17: Estamos definiendo nuestra Story

Línea 19: Aquí estamos definiendo los props para el componente Default, que recibirá un title y un message

Y el resultado será este 👇

¡Y listo, es así de simple! 🎉

Vamos a agregar las otras variantes de nuestro Alert 👇

La diferencia aquí es que se agregó el prop type dentro de args, automáticamente Storybook listará todas las variantes del componente 👇

El archivo final Alert.stories.js quedó así 👇

// Alert.stories.js
import React from "react";

import Alert from "./Alert";

export default {
  title: "Alert",
  component: Alert,
  argTypes: {
    type: {
      control: "select",
      defaultValue: "default",
      options: ["default", "info", "success", "danger", "warning"],
    },
  },
};

export const Default = (args) => <Alert {...args} />;
Default.args = {
  title: "Alert example",
  message:
    "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer vestibulum neque est, at laoreet dolor bibendum eu.",
};

export const Info = (args) => <Alert {...args} />;
Info.args = {
  title: "Alert example",
  type: "info",
  message:
    "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer vestibulum neque est, at laoreet dolor bibendum eu.",
};

export const Success = (args) => <Alert {...args} />;
Success.args = {
  title: "Alert example",
  type: "success",
  message:
    "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer vestibulum neque est, at laoreet dolor bibendum eu.",
};

export const Danger = (args) => <Alert {...args} />;
Danger.args = {
  title: "Alert example",
  type: "danger",
  message:
    "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer vestibulum neque est, at laoreet dolor bibendum eu.",
};

export const Warning = (args) => <Alert {...args} />;
Warning.args = {
  title: "Alert example",
  type: "warning",
  message:
    "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer vestibulum neque est, at laoreet dolor bibendum eu.",
};

¡Y listo, creamos nuestra primera Story, así de sencilla! 😎

Si quieres ejecutar la aplicación en tu máquina, puedes acceder al repositorio en este enlace.