Mettre en place StoryBook sur un projet React

Article écrit par Cédrick Guerin

Storybook est un outil open source qui permet de créer des composants isolés à des fins de documentation.

Dans le cadre d’un de nos projets, j’ai été chargé de mettre en place Storybook pour écrire une documentation intuitive, claire et compréhensible de tous (même pour ceux qui ne connaissent pas React).

Prérequis :

• Avoir un projet React initialisé

Installation de Storybook

Tout d’abord, vous devrez installer Storybook sur votre projet. Pour ce faire, placez-vous a la racine de votre projet React et exécutez la commande suivante :

npx sb init

Elle s’occupera d’installer les dépendances requises, configurer les scripts pour exécuter StoryBook, ajouter la configuration par défaut de Storybook et une story par défaut pour avoir un exemple.

Vous verrez maintenant un dossier .storybook a la racine de votre projet contenant 2 fichiers :

main.js

preview.js

Le fichier main.js est le fichier principal de la configuration pour builder votre documentation Storybook.

Dans la configuration actuelle, il ira chercher tous les fichiers qui finissent par .stories.mdx et .stories.js|jsx|ts|tsx pour builder votre doc.

Il ajoute également par défaut 2 Addons.

Addons

Storybook propose plusieurs addons supplémentaires à installer pour alimenter encore plus notre documentation. Celui que j’utilise le plus (et aussi celui que je préfère est addon-docs).

Pour l’installer, il suffit d’éxécuter la commande :

npm i @storybook/addon-docs

Il faut également le rajouter dans le fichier main.js (mentionné plus haut)

Il faut visualiser les addons comme des onglets dans notre documentation.

addon-docs permet :

• D’inclure des snippets de code pour mieux comprendre comment utiliser notre composant
• D’afficher toutes les props attendues par le composant (type, valeurs autorisées, valeur par défaut, etc…)
• D’afficher des bouts de codes que nous souhaitons écrire (comme un import spécifique qu’il faut mettre en place avant d’utiliser notre composant)

Vous pouvez retrouver la liste des addons disponibles ici.

Ecrire une story

Une story est une page a part entière de la documentation générée expliquant le fonctionnement et l’utilisation d’un composant.

Storybook nous offre 2 façons d’écrire une story (sur un projet React codé en TypeScript) :

• En Markdown (MDX)
• En Typescript (TSX)

Nous allons nous concentrer sur l’écriture en MDX.

Admettons que nous ayons un composant InfoBulle dans notre projet.

Vous devrez rajouter un fichier InfoBulle.stories.mdx dans le folder de votre composant. C’est dans ce fichier que vous écrirez votre template (cf. exemple ci-dessous).

Une fois vos stories terminées, éxécutez la commande :

npm run storybook

Une page web s’ouvre et tadaaam votre documentation est prête.

Voilà ! Vous savez maintenant mettre en place Storybook sur un projet React et écrire votre documentation.

Vous pouvez retrouver la doc officielle de storybook ici.