Storybook : documenter et tester ses composants UI
Guide complet Storybook : configuration, stories, addons et tests visuels pour documenter vos composants React.
Storybook est l'outil de developpement isole de composants le plus adopte dans l'ecosysteme React et Next.js, avec plus de 80 000 etoiles sur GitHub. Il permet de developper, tester et documenter chaque composant UI independamment de l'application, accelerant le cycle de developpement et ameliorant la qualite du design system.
L'approche Component-Driven Development (CDD) promue par Storybook inverse le processus de developpement classique : au lieu de construire des pages entieres, on developpe d'abord les composants atomiques, puis on les compose en patterns de plus en plus complexes. Cette methodologie reduit les bugs, facilite les revues de code et produit des composants naturellement plus reutilisables.
Ce guide couvre la configuration de Storybook 8 avec Next.js, l'ecriture de stories avec le format CSF3, l'utilisation des controls et addons, ainsi que les strategies de test visuel et d'accessibilite. Vous decouvrirez comment transformer Storybook en hub central de documentation pour votre equipe.
1. Installation et configuration avec Next.js
L'initialisation de Storybook dans un projet Next.js se fait via npx storybook@latest init qui detecte automatiquement le framework et configure le builder Webpack ou Vite. Le framework @storybook/nextjs gere nativement les specificites de Next.js : next/image, next/link, next/font, next/navigation et les CSS Modules. La configuration reside dans .storybook/main.ts et .storybook/preview.ts.
Le fichier main.ts definit les patterns de decouverte des stories (stories: ['../src/**/*.stories.@(ts|tsx)']), les addons actifs et la configuration du framework. Le fichier preview.ts configure les decorators globaux, les parametres par defaut et les mocks des providers React (ThemeProvider, IntlProvider). Chaque story herite automatiquement de cette configuration globale.
Pour les projets utilisant Tailwind CSS, le fichier preview.ts doit importer la feuille de style globale (import '../src/app/globals.css') afin que les classes Tailwind soient disponibles dans les stories. Les path aliases (@/components) se configurent dans le webpackFinal ou viteFinal du main.ts en reprenant la configuration tsconfig.json du projet.
2. Ecriture de stories avec le format CSF3
Le format Component Story Format 3 (CSF3) utilise des exports nommes pour definir les stories d'un composant. L'export default (meta) contient le titre, le composant, les argTypes et les decorators. Chaque export nomme represente une story avec ses args specifiques. Par exemple, export const Primary: Story = { args: { variant: 'primary', label: 'Cliquer ici' } } definit une story avec des props preconfigurees.
Le typage TypeScript des stories utilise le generique Meta<typeof Component> et StoryObj<typeof meta> qui garantissent que les args correspondent exactement aux props du composant. L'autocompletion et la verification de type detectent les props manquantes ou incorrectes au moment de l'ecriture, eliminant une categorie entiere d'erreurs avant meme l'execution.
Les decorators permettent d'encapsuler une story dans un contexte specifique : un wrapper de mise en page, un provider de theme ou un conteneur avec des dimensions fixes. Un decorator se definit comme une fonction recevant la Story et le context, retournant le JSX enrichi. Les decorators se declarent au niveau de la story, du composant (meta) ou globalement dans preview.ts.
3. Args, Controls et addons essentiels
Les Controls generent automatiquement un panneau interactif dans Storybook permettant de modifier les props du composant en temps reel. Les argTypes definissent le type de controle pour chaque prop : select pour les enums, range pour les nombres, color pour les couleurs, radio pour les choix exclusifs. La propriete table.category organise les controles en groupes logiques pour les composants avec de nombreuses props.
L'addon Actions enregistre et affiche les appels aux callbacks du composant (onClick, onChange, onSubmit) dans un panneau dedie. La configuration argTypes: { onClick: { action: 'clicked' } } loggue automatiquement chaque clic. L'addon Interactions va plus loin en permettant d'ecrire des scenarios de test step-by-step avec play functions utilisant @storybook/test (userEvent.click, expect).
Les addons de documentation (@storybook/addon-docs) transforment vos stories en pages de documentation interactive avec MDX. L'autodocs genere automatiquement une page de documentation pour chaque composant, incluant la table des props, les exemples interactifs et les stories. L'addon a11y (@storybook/addon-a11y) integre axe-core pour analyser chaque story et signaler les violations d'accessibilite WCAG.
Besoin d’aide en Technologie ?
Nos experts vous accompagnent. Recevez 3 devis gratuits sous 24h.
Gratuit · Sans engagement · Reponse sous 24h
4. Tests visuels et tests d'interaction
Les tests visuels comparent des captures d'ecran de chaque story entre les commits pour detecter les regressions CSS involontaires. Chromatic, la plateforme officielle de Storybook, automatise ce processus dans la CI en capturant chaque story dans plusieurs navigateurs et viewports. Les differences visuelles sont presentees dans une interface de revue ou l'equipe peut approuver ou rejeter chaque changement.
Les play functions transforment les stories en tests d'interaction automatises. Dans la propriete play de la story, on utilise userEvent pour simuler des clics, des saisies et des navigations clavier, puis expect pour verifier le resultat. La commande test-storybook execute toutes les play functions en mode headless dans la CI, fournissant un rapport de couverture et des messages d'erreur detailles.
La combinaison de tests visuels (apparence) et de tests d'interaction (comportement) dans Storybook couvre la majorite des scenarios de test front-end sans necessiter de framework de test supplementaire. L'addon coverage genere des rapports de couverture de code compatibles Istanbul, permettant de mesurer precisement quelles lignes et branches du composant sont exercees par les stories.
5. Documentation et design system
Storybook sert de source de verite vivante pour le design system en presentant chaque composant avec ses variantes, ses props documentees et ses regles d'utilisation. Les fichiers MDX (.mdx) dans le dossier stories permettent de rediger des pages de documentation libre combinant du texte Markdown, des composants React interactifs et des stories embarquees via le composant <Story />.
L'organisation hierarchique des stories (Atoms/Button, Molecules/SearchBar, Organisms/Header) reflete l'architecture atomic design du design system. La sidebar de Storybook devient un catalogue navigable ou designers et developpeurs peuvent explorer, tester et copier les composants disponibles. Le tag 'autodocs' dans le meta genere automatiquement une page de reference pour chaque composant.
Le deploiement de Storybook en tant que site statique (npm run build-storybook) produit un ensemble de fichiers HTML hebergeables sur n'importe quel CDN. Chromatic ou GitHub Pages servent couramment de plateforme d'hebergement, offrant a toute l'equipe (design, produit, QA) un acces permanent a la documentation des composants sans avoir besoin d'un environnement de developpement local.
Questions frequentes
Storybook ralentit-il le build de mon application Next.js ?
Non, Storybook fonctionne comme un processus completement separe avec son propre serveur de developpement et son propre build. Il n'affecte ni le temps de build ni les performances de votre application en production. Seul le temps de demarrage de Storybook lui-meme peut etre optimise en limitant le nombre d'addons charges.
Comment mocker les API et les donnees dans les stories ?
L'addon msw-storybook-addon integre Mock Service Worker pour intercepter les requetes reseau au niveau du service worker. Chaque story peut definir ses propres handlers MSW via le parametre msw, retournant des donnees specifiques au scenario illustre. Cette approche est plus fiable que les mocks manuels car elle intercepte les vraies requetes fetch.
Faut-il ecrire une story pour chaque composant ?
Les composants partages et reutilisables (boutons, inputs, modals, cards) meritent des stories detaillees couvrant toutes les variantes. Les composants de page specifiques ou les wrappers simples n'ont pas besoin de stories individuelles. La regle pratique est de couvrir tout composant qui apparait dans plus d'un endroit de l'application.
Comment integrer Storybook dans un pipeline CI/CD ?
Ajoutez deux etapes dans votre CI : build-storybook pour verifier que toutes les stories compilent correctement, et test-storybook --ci pour executer les play functions et les tests d'accessibilite. Chromatic s'integre en une ligne (npx chromatic --project-token=xxx) pour ajouter les tests visuels de regression.
Storybook 8 supporte-t-il les React Server Components ?
Storybook 8 avec le framework @storybook/nextjs rend les Server Components comme des composants clients classiques dans l'environnement isole. Les fonctionnalites serveur (acces base de donnees, file system) doivent etre mockees. La strategie recommandee est de separer la logique serveur dans des fonctions utilitaires facilement mockables.
Guides complementaires
Next.js 14 : guide complet du App Router en français
Guide complet du App Router Next.js 14 en français : layouts, server components, data fetching et déploiement.
TechnologieTailwind CSS : guide complet et bonnes pratiques 2025
Guide complet Tailwind CSS : configuration, responsive design, dark mode, composants réutilisables et bonnes pratiques.
TechnologieAPI REST vs GraphQL : quel choix pour votre projet
Comparatif détaillé REST vs GraphQL : performances, flexibilité, sécurité et cas d'usage pour choisir votre API.
Outils gratuits recommandes
Lancez votre projet technologie
500+ experts verifies prets a vous accompagner. Devis gratuit sous 24h.