Para llevar a cabo la escritura de stories y la documentación vamos a seguir algunas recomendaciones. Mediante el proceso de linting nos comprometemos a seguir correctamente unas buenas prácticas a la hora de escribir.

Para ello, nos apoyaremos en el eslint y unos packages para poner a punto una configuración de reglas que deberemos cumplir. Este cumplimiento lo podremos ver tanto en el proceso de escritura (mediante extensiones del editor de código) así como también en la ejecución del proceso de lint para garantizar la calidad de código.

Como premisa, se entenderá que ya se tiene instalado el eslint así como un archivo de configuración clásica (.eslintrc.json) y su ejecución podría ser:

npx nx run-many --target=lint --all --parallel

Lint para stories

Para escribir bien las stories instalaremos el package eslint-plugin-storybook:

npm install --save-dev eslint-plugin-storybook

Y modificaremos nuestro archivo de configuración del eslint para activar las reglas dentro del perfil “recommended” (hay otras configuraciones pero esta ya nos vale) de la siguiente manera:

{
  // extend plugin:storybook/, such as:
  "extends": ["plugin:storybook/recommended"]
}

Este complemento solo se aplicará a archivos que sigan el patrón *.stories.* (que es el  recomendado) o *.story.*. Esta es una configuración automática, por lo que no se tiene que hacer nada.

Si existiera algún conflicto entre reglas (por ejemplo en el naming-convention) o queremos modificar alguna para las stories entonces podríamos sobreescribir esa regla:

{
  "files": ["*.stories.@(ts|tsx|js|jsx|mjs|cjs)"],
  "extends": ["plugin:storybook/recommended"],
  "rules": {
    // Ejemplo para sobreescribir una regla de storybook
    "storybook/hierarchy-separator": "error",
    // Ejemplo para deshabilitar una regla de storybook
    "storybook/default-exports": "off",
    // Ejemplo para sobreescribir una regla de @typescript
    "@typescript-eslint/naming-convention": [
      "error",
      {
        "selector": "variable",
        "format": ["camelCase", "PascalCase"],
        "leadingUnderscore": "allow",
        "trailingUnderscore": "forbid"
      }
    ]
}

Lint para documentación

Para escribir bien la dpcumentación en los archivos MDX instalaremos el package eslint-plugin-mdx:

npm install --save-dev eslint-plugin-mdx

Activaremos su configuración «recommended» para este tipo de archivos. Además nos interesará que el código escrito en sus bloques de código estén bien escritos con lo que activaremos su regla code-blocks (por defecto está desactivado):

{
  "files": ["*.mdx"],
  "extends": ["plugin:mdx/recommended"],
  "settings": {
    "mdx/code-blocks": true
  }
}

Extensiones VS Code

Es de mucha utilidad tener unas extensiones instaladas y activadas en nuestro entorno de edición para que nos ayude mientras trabajamos. Estas extensiones las podemos ver en el marketplace de extensiones de VS Code.

Eslint

Extensión ESLint

Gracias a este complemento podremos visualizar en el editor en qué nos estamos equivocando indicándonos qué regla del eslint está dando el error. Esta extensión la podemos encontrar en https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint o también buscándola a través del apartado extensiones del VS Code.

MDX

Extensión MDX

Gracias a esta extensión, VSCode podrá soportar (y visualizar mejor) los archivos de lenguaje MDX ya que por sí solo no puede reconocerlo y lo veríamos como un archivo de texto.
Esta extensión la podemos encontrar en https://marketplace.visualstudio.com/items?itemName=unifiedjs.vscode-mdx  o también buscándola a través del apartado extensiones del VS Code.

Resumen

Gracias al papel que hace el linter, podemos escribir tanto las stories como la documentación siguiendo unas recomendaciones.

Además podemos ayudarnos de extensiones de VSCode para que dentro de nuestro entorno de trabajo nos ayude a visualizar mejor nuestro código además de indicarnos en qué nos estamos equivocando.