TECHNOLOGIES
Storybook, notre outil de documentation de composants Vue.js
Storybook est un environnement de développement isolé pour les composants UI. Il nous permet de développer, documenter et tester chaque composant Vue.js indépendamment du reste de l'application.
Chez SmartBooster, Storybook est l'outil de référence pour nos projets Vue.js autonomes : documentation technique des composants, règles de parcours métier et référence de paramétrage pour les Web Components.
PRÉSENTATION
Qu'est-ce que Storybook ?
Storybook est un outil open source qui crée un environnement de développement isolé pour vos composants UI. Chaque composant est décrit par des stories → des scénarios qui illustrent ses différents états et variantes. L'ensemble forme une documentation interactive navigable dans le navigateur.
Storybook s'intègre nativement avec Vue.js et Vite. Il supporte TypeScript, les composants script setup et l'ensemble de l'écosystème Vue 3. Les stories peuvent être écrites en format .stories.ts ou en MDX pour les pages de documentation plus riches.
Au-delà de la documentation de composants, Storybook permet d'enrichir la base de connaissance du projet avec des pages dédiées : schémas de parcours, règles métier, description de paramétrage → une seule référence accessibles à toute l'équipe.
POURQUOI STORYBOOK
Ce qui en fait notre outil de documentation de référence
Storybook résout plusieurs problèmes à la fois : documentation qui vieillit mal, composants difficiles à tester en isolation, manque de référence partagée entre développeurs et produit.
Documentation vivante des composants
Chaque composant Vue.js est documenté dans Storybook avec ses variantes, ses props et ses états. La documentation vit dans le code et reste toujours à jour sans effort de synchronisation avec un wiki externe.
Développement en isolation
Storybook permet de développer et tester un composant hors de son contexte applicatif. Moins de dépendances à simuler, moins de temps perdu à reproduire un état précis pour tester un rendu particulier.
Parcours et règles métier
Au-delà des composants UI, nous créons des pages Storybook dédiées pour documenter les schémas de parcours utilisateur et les règles métier complexes. Une source de vérité partagée entre l'équipe technique et les parties prenantes.
Paramétrage des Web Components
Pour les projets exposant des Web Components configurables, Storybook documente chaque paramètre disponible avec des exemples interactifs. Les intégrateurs disposent d'une référence claire et testable en direct.
Détection des régressions visuelles
En couplant Storybook à des tests de snapshot, toute modification de composant est immédiatement visible. Les régressions visuelles sont détectées avant qu'elles n'atteignent la production.
Collaboration avec les équipes produit
Storybook produit une interface navigable accessible à tous. Les équipes produit et design peuvent valider les composants directement dans le navigateur sans avoir à lancer l'application complète.
NOTRE USAGE
Comment nous utilisons Storybook chez SmartBooster
Nous utilisons Storybook dans les projets Vue.js autonomes, en particulier quand une bibliothèque de composants est construite ou quand des Web Components configurables sont exposés à des équipes tierces.
Projets Vue.js autonomes
Nous intégrons Storybook dans nos projets Vue.js dès lors qu'une bibliothèque de composants est développée. Chaque composant est documenté avec ses stories couvrant les états principaux : défaut, chargement, erreur, variantes.
Pages de documentation métier
En complément des stories de composants, nous créons des pages MDX dans Storybook pour documenter les schémas de parcours, les règles de validation et les cas limites. Ces pages servent de référence partagée entre développeurs et responsables produit.
Référence pour les Web Components
Quand un projet expose des Web Components intégrables par des tiers, Storybook documente chaque attribut, événement et slot disponible avec des exemples configurables en direct via les Controls.
EN PRATIQUE
Ce que Storybook nous permet de faire
Au-delà de la documentation, Storybook est un véritable environnement de travail : développement isolé, tests automatisés avec Playwright et validation visuelle par les équipes produit.
Story dédié pour chaque composant
Chaque composant dispose de son propre fichier .stories.ts qui regroupe ses différentes stories : chaque story représente un état ou une variante précise du composant (état par défaut, variante désactivée, message d'erreur…).
La page Docs générée automatiquement par Storybook avec l'addon @storybook/addon-docs affiche le rendu réel du composant dans un Canvas interactif, accompagné de la description, du code source de la story et du tableau des Controls. Les Controls sont générés automatiquement depuis les args du composant : ils permettent de modifier les props en temps réel directement dans le navigateur, sans toucher au code.
C'est à la fois un outil de développement pour l'équipe technique et une référence navigable pour les équipes produit qui peuvent explorer et valider chaque variante sans lancer l'application complète.
Page de documentation complémentaire au format MDX
En plus des stories de composants, Storybook permet d'ajouter des pages de documentation libres au format MDX (Markdown + JSX). Ces pages vivent dans la même interface Storybook et peuvent intégrer des composants rendus en direct, des tableaux de référence ou des extraits de code.
Ce format est particulièrement utile pour documenter ce qui dépasse le composant lui-même : règles de parcours utilisateur et cas limites pour l'équipe produit, guide d'intégration et liste des attributs pour une équipe support ou marketing qui intègre des Web Components, conventions de code et décisions d'architecture pour l'équipe technique.
Toute la documentation, composants et pages MDX, est regroupée dans une seule interface navigable et versionnée avec le code. Elle ne se désynchronise pas, contrairement à un wiki ou un Notion mis à jour manuellement.
Tester les interactions de vos composants
L'addon @storybook/addon-vitest transforme vos stories en tests de composants exécutés dans un vrai navigateur via Vitest et Playwright. Ajoutez une fonction play à une story pour scripter les interactions : clic, saisie, navigation, vérification d'un état résultant.
Les résultats s'affichent story par story dans le panneau Interactions de l'interface Storybook. Les étapes réussies et échouées sont détaillées, ce qui facilite le débogage sans quitter l'environnement de développement.
C'est particulièrement utile pour valider des composants avec des états complexes : formulaires, modales, menus déroulants. Chaque story annotée devient un test de non-régression fonctionnel.
Vérifier les règles d'accessibilité de vos composants
L'addon @storybook/addon-a11y intègre le moteur axe-core dans Storybook pour vérifier automatiquement les règles d'accessibilité de chaque composant. Contraste des couleurs, attributs ARIA, structure des titres : les violations sont signalées dans le panneau Accessibility de l'interface.
Quand l'addon Vitest est installé, les tests d'accessibilité s'activent depuis le widget de test de la barre latérale. Les résultats apparaissent story par story avec un indicateur de statut, sans outil externe ni configuration supplémentaire.
Les violations sont catégorisées par gravité (critique, sérieuse, modérée) et accompagnées de recommandations de correction directement dans l'interface.
Détecter les changements visuels dans vos UI avec les tests Chromatic
Chromatic est un service cloud de tests visuels développé par l'équipe Storybook. L'addon @chromatic-com/storybook connecte votre projet à Chromatic pour capturer un screenshot de chaque story et le comparer pixel par pixel à la référence précédente.
Depuis un script package.json dédié (lançable à la main ou depuis un job dédié en CI), Chromatic met en évidence les diffs visuels détectés. Chaque changement doit être approuvé ou rejeté par l'équipe avant le merge, ce qui évite qu'une modification de HTML ou CSS (voir JS) impacte discrètement d'autres composants.
C'est un filet de sécurité efficace sur les projets avec de nombreux composants : les régressions visuelles sont détectées automatiquement, sans avoir à inspecter chaque écran après chaque modification.
Contrôler la couverture de vos tests Storybook
L'addon @storybook/addon-vitest permet de calculer la couverture de code exercée par vos stories depuis l'interface Storybook avec la checkbox Coverage.
Vous pouvez ensuite cliquez sur le pourcentage pour avoir un tableau récapitulatif par dossier de la couverture.
Le rapport généré indique quelles lignes de code sont couvertes par vos stories, de façon complémentaire aux tests unitaires de Vitest. Vous obtenez une vue séparée de la couverture apportée spécifiquement par Storybook.
Cette granularité permet d'identifier les composants sans story et de mesurer concrètement la valeur de votre bibliothèque de composants en termes de couverture de test.
Automatiser les tests depuis votre CI grâce à la CLI Storybook
La commande storybook test (ou npm run test-storybook) lance l'ensemble des tests de composants Storybook depuis le terminal, sans ouvrir l'interface graphique. C'est le point d'entrée pour intégrer Storybook dans votre pipeline CI.
Elle exécute en mode headless toutes les stories avec une fonction play, les tests d'accessibilité activés et la couverture si le flag --coverage est ajouté. Un seul step GitHub Actions ou job Gitlab suffit pour couvrir l'ensemble.
Chaque push déclenche ainsi la suite complète : interactions, accessibilité et couverture en une seule commande. Les tests Storybook deviennent un garde-fou intégré au workflow Git, au même titre que les tests unitaires.
BONNES PRATIQUES & DOCUMENTATION
Nos conventions Storybook
Documentation de référence pour l'équipe SmartBooster.
Comment dissocier la config des tests unitaire de la config Storybook dans Vitest ?
Comment dissocier la config des tests unitaire de la config Storybook dans Vitest ?
La vitest.config.ts possède un paramètre projects qui permet scinder la configuration entre les tests unitaires et les tests Storybook.
Voici un exemple de code de séparation entre les deux types de tests :
export default mergeConfig(viteConfig({
mode: 'test'
}), defineConfig({
test: {
reporters: process.env.CI ? ['default', ['junit', {
outputFile: 'coverage/junit.xml'
}]] : ['default'],
coverage: {
provider: 'v8',
reportsDirectory: './coverage',
reporter: ['html', 'text', 'text-summary', 'cobertura'],
},
projects: [
{
extends: true,
test: {
name: 'unit',
globals: true,
environment: 'jsdom',
isolate: false,
setupFiles: ['./tests/unit/setup-locale.js'],
include: ['tests/unit/**/*.spec.{js,ts}'],
css: false
}
},
{
extends: true,
plugins: [
storybookTest({
configDir: path.join(dirname, '.storybook')
})
],
test: {
name: 'storybook',
browser: {
enabled: true,
headless: true,
provider: playwright({}),
instances: [{
browser: 'chromium'
}]
}
}
}
]
}
}));
Pour aller plus loin
Documentation utile
Documentation complète, addons et guides pour démarrer avec Storybook.
Guide de démarrage officiel pour intégrer Storybook dans un projet Vue 3 + Vite.
Pour aller plus loin
Approfondir votre réflexion
Storybook est notre outil de documentation des composants Vue.js. Ensemble, ils forment la base de nos design systems sur mesure.
Storybook documente les composants réutilisables de nos projets, facilitant la collaboration et la cohérence visuelle dans la durée.
Une bibliothèque de composants bien documentée sous Storybook accélère les évolutions et réduit le risque de régression visuelle en maintenance.