Documenter son projet avec Storybook

La documentation technique d’un projet est malheureusement une phase souvent négligée, voire complètement sacrifiée par manque de temps. 

Pourtant il nous est tous déjà arrivé de devoir faire un petit correctif sur un projet que nous n’avons pas développé. L’apprentissage des rouages de ce dernier se fait plus ou moins lentement et plusieurs questions peuvent alors se poser : 

• “Est-ce que je peux utiliser un composant existant ou dois-je créer le mien ?”
• “Ce composant a l’air de répondre à mon besoin, mais comment en être sûr à 100%  ?”
• “Je dois faire évoluer un composant mais j’ai un peu peur de tout casser, que faire ?”

Etc, etc…

Qu’est-ce que Storybook ?

Storybook est un outil Open-Source permettant de développer des composants isolés pour React, Vue et Angular.

Voici la vidéo de présentation :

Vous trouverez également ici tout un tas d’exemples d’utilisation de Storybook.

Intégration dans un projet

L’intégration de Storybook dans les projets a été simplifiée au maximum, si bien qu’une seule ligne de commande suffit

npx -p @storybook/cli sb init --type <le-framework-utilisé>

Donc par exemple pour un projet Angular

npx -p @storybook/cli sb init --type angular

Cela va faire plusieurs choses :

• Créer un dossier .storybook à la racine du projet qui contiendra entre autres
  • Un fichier addons.js (nous reviendrons plus tard sur ce fichier)
  • 2 fichiers de configurations
• Créer un dossier stories avec un fichier index.stories.js qui contient quelques exemples.
• Ajouter des devDependencies au package.json ainsi que 2 scripts.

Nous pouvons maintenant exécuter la commande suivante 

npm run storybook

Une page doit automatiquement s’ouvrir et doit ressembler à peu de chose près à ceci :

Vous pouvez déjà tester quelques fonctionnalités, par exemple en allant dans Button > with some emoji and action et en cliquant sur le bouton vous devriez voir qu’une action a été lancée dans le panel Actions 

Contenu d’une story

Regardons maintenant de plus près le fichier index.stories.js et attardons nous plus en détail sur sa composition.

storiesOf

La méthode storiesOf permet de créer une nouvelle story, nous pouvons lui donner le nom que l’on souhaite. 

Attention toutefois car cela définit également l’arborescence de vos stories. Par exemple :

storiesOf(‘toto’) va créer l’arborescence suivante 

• toto

storiesOf(‘toto|tata’) va créer l’arborescence suivante

• toto
  • tata

storiesOf(‘toto|tata\titi’) va créer l’arborescence suivante

• toto
  • tata
    • titi

Etc etc…

add

La méthode add est directement liée à la méthode storiesOf et permet, comme son nom l’indique, d’ajouter un cas d’utilisation au composant testé. En terme d’arborescence cela va ajouter le cas comme fils direct du dossier définit dans la méthode storiesOf.

Par exemple 

storiesOf(‘toto’).add(‘tata’) va créer l’arborescence suivante

• toto
  • tata

Sauf que cette fois-ci tata ne sera pas considéré comme un dossier mais comme un fichier.

Le 2e paramètre de la méthode add retourne le composant à tester dans la configuration souhaitée.

En React cela donnerait 

import React from 'react';
import { storiesOf } from '@storybook/react';
import { Button } from '@storybook/react/demo';

storiesOf('Button', module)
  .add('with text', () => (
    <Button>Hello Button</Button>
  ))
  .add('with emoji', () => (
    <Button><span role="img" aria-label="so cool">😀 😎 👍 💯</span></Button>
  ));   

En Vue

import Vue from 'vue';
import { storiesOf } from '@storybook/vue';
import MyButton from './Button.vue';

storiesOf('Button', module)
  .add('with text', () => '<my-button>with text</my-button>')
  .add('with emoji', () => '<my-button>😀 😎 👍 💯</my-button>')
  .add('as a component', () => ({
    components: { MyButton },
    template: '<my-button :rounded="true">rounded</my-button>'
  }));

En Angular

import { storiesOf } from '@storybook/angular';
import { Button } from '@storybook/angular/demo';

storiesOf('My Button', module)
 .add('with text', () => ({
    component: Button,
    props: {
      text: 'Hello Button',
    },
  }))
  .add('with emoji', () => ({
    component: Button,
    props: {
      text: '😀 😎 👍 💯',
    },
  }));

 

Le 3e paramètre permet d’éventuellement ajouter une note à notre test. Cette note peut prendre différents formats, notamment le markdown, ce qui permet de documenter de manière très poussée.

Voici un exemple sur un projet existant :

En terme de code cela donnerait par exemple en Angular

import { storiesOf } from '@storybook/angular';

import { Button } from '@storybook/angular/demo';

storiesOf('Button', module)
  .add(
    'with some emoji',
    () => ({
      component: Button,
      props: {
        text: '😀 😎 👍 💯',
      },
    }),
    { notes: <ici les notes à afficher au format souhaité> }
  )

Créer sa première story

Si vous jeter un coup d’oeil au fichier config.js qui se trouve dans le dossier .storybook vous remarquerez que Storybook scanne votre projet à la recherche des fichiers se terminant par stories.js.

Pour créer une nouvelle story il suffit donc simplement de créer un nouveau fichier se terminant par stories.js, n’importe où dans le projet.

Ajout d’addons

Lorsqu’on initialise Storybook, nous avons la possibilité de voir les actions lancées et/ou les notes. Il est possible par la suite d’en ajouter d’autres.

Rajoutons ensemble un addon permettant de modifier la taille de notre viewport. 

Commençons par installer la dépendance de dev

npm i --save-dev @storybook/addon-viewport

Puis ajouter la ligne suivante à la fin du fichier addons.js

import '@storybook/addon-viewport/register';

Et c’est tout ! Normalement une icône devrait apparaître à coté des notes. Cela permettra de modifier la taille du viewport et donc de tester la responsivité de notre composant.

En pratique

La bonne pratique en terme d’architecture est de regrouper l’ensemble des cas possibles d’un composant dans la même story pour avoir rapidement une vue synthétique.

Et pour tester que notre composant réagit bien au changement de taille

Conclusion

Storybook est un outil très facile à installer et à prendre en main. Il permet de tester en profondeur les composants (fonctionnalités, réactivé au changement de taille, etc). L’outil vous permet indirectement de proposer aux utilisateurs une liste des composants utilisables avec une documentation attachée à chacun d’eux, et ça, c’est top !