Tous les articles

Front-end11 min de lecture

Storybook : comment démarrer et jusqu'où aller

Storybook 10 de zéro : installer, écrire des stories, tester l'interaction et l'accessibilité dans Vitest et décider, niveau par niveau, jusqu'où aller.

Aussi en Português, English, Español

Storybook fait partie de ces outils dont tout le monde a entendu parler et que peu de gens utilisent bien. Soit le projet ne l'installe jamais, soit il l'installe, écrit trois stories pour le bouton et l'abandonne, soit il essaie de tout couvrir et finit par passer plus de temps à maintenir des stories qu'à construire des écrans.

Cet article prend la voie du milieu : il montre comment démarrer en quelques minutes et organise la suite en niveaux, pour que vous décidiez jusqu'où il est utile d'aller dans votre projet.

Une précision honnête : tout ici a été fait dans un vrai projet avec Storybook 10.6, React 19 et Vite. Les stories de l'article tournent comme des tests et passent, et la vérification d'accessibilité a été confirmée en cassant volontairement une story avec un bouton sans nom.

TL;DR#

  • Storybook est une vitrine pour vos composants, en dehors de l'application, dans tous leurs états : vide, en chargement, en erreur, avec un texte énorme.
  • Démarrer tient en une commande : npm create storybook@latest. Elle détecte le framework et configure déjà les tests et l'accessibilité.
  • Une story, c'est juste un composant avec des données. Le format actuel (CSF) est un objet avec des args.
  • Les stories deviennent des tests. Avec l'addon Vitest, chaque story s'affiche dans un vrai navigateur, et play simule le clic et vérifie le résultat.
  • Jusqu'où aller : pour presque tous les projets, des stories pour les composants visuels, des tests d'interaction et l'accessibilité suffisent. Les tests visuels et une documentation soignée ont du sens dans un design system et des composants partagés.
  • N'écrivez pas de stories pour des pages qui dépendent d'une API. Une bonne story concerne un composant qui reçoit tout par props.

À quoi ça sert#

Sans Storybook, pour voir un composant dans un état précis, il faut naviguer dans l'application jusqu'au bon écran, avec les bonnes données. Voir la carte de commande avec un nom de client énorme, c'est créer un client avec un nom énorme. Voir la liste vide, c'est supprimer les commandes.

Avec Storybook, chaque état devient une story : une entrée fixe qui s'ouvre en un clic. Cela aide pour quatre choses :

  • Développer le composant isolément, sans dépendre du backend, de la connexion ou de la navigation.
  • Repérer les cas limites qui n'apparaissent presque jamais dans l'application : texte long, liste vide, valeur nulle.
  • Échanger avec le design et le produit, en montrant tous les états au même endroit.
  • Tester, car chaque story peut devenir un test automatique.

Niveau 0 : installer#

Dans un projet existant, à la racine :

npm create storybook@latest

L'installeur examine les dépendances du projet et choisit la configuration. Dans un projet avec React et Vite, la version 10.6 a installé :

  • Storybook avec le framework @storybook/react-vite ;
  • @storybook/addon-vitest, qui transforme les stories en tests ;
  • @storybook/addon-a11y, qui lance la vérification d'accessibilité ;
  • @storybook/addon-docs, qui génère la page de documentation de chaque composant ;
  • @storybook/addon-mcp, l'intégration avec les assistants IA (plus à la fin) ;
  • Playwright avec Chromium, que les tests utilisent pour afficher les stories.

Et il a créé deux scripts :

npm run storybook        # opens Storybook at localhost:6006
npm run build-storybook  # generates a static site in storybook-static/

La configuration se trouve dans .storybook/ :

.storybook/main.ts
import type { StorybookConfig } from '@storybook/react-vite';
 
const config: StorybookConfig = {
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  addons: [
    '@chromatic-com/storybook',
    '@storybook/addon-vitest',
    '@storybook/addon-a11y',
    '@storybook/addon-docs',
    '@storybook/addon-mcp',
  ],
  framework: '@storybook/react-vite',
};
 
export default config;

L'installeur crée aussi un dossier src/stories avec des exemples (bouton, en-tête, page). Il vaut la peine d'y jeter un œil une fois, puis de le supprimer.

Cela fonctionne aussi avec Angular : la documentation indique Angular 18 ou plus récent, et les concepts ci-dessous sont les mêmes. Les exemples de cet article sont en React.

Niveau 1 : des stories pour les composants visuels#

Les exemples utilisent les composants d'une liste de commandes, les mêmes que dans l'article sur les composants smart et dumb : OrderCard, OrderList et StatusFilter. Ils reçoivent tout par props, et c'est justement pour ça qu'ils sont faciles à mettre dans Storybook.

Une story vit à côté du composant, dans un fichier .stories.tsx :

OrderCard.stories.tsx
import type { Meta, StoryObj } from '@storybook/react-vite';
import { expect, fn } from 'storybook/test';
import { OrderCard } from './OrderCard';
 
const meta = {
  title: 'Orders/OrderCard',
  component: OrderCard,
  tags: ['autodocs'],
  args: {
    order: { id: '42', customer: 'Ana Souza', total: 189.9, status: 'paid' },
    onSelect: fn(),
  },
} satisfies Meta<typeof OrderCard>;
 
export default meta;
type Story = StoryObj<typeof meta>;
 
export const Default: Story = {};
 
export const Selected: Story = {
  args: { selected: true },
};
 
export const LongCustomerName: Story = {
  args: {
    order: { id: '43', customer: 'Maria Aparecida dos Santos Albuquerque Ferreira', total: 12999.5, status: 'pending' },
  },
};
 
export const ClickingDetailsSendsTheId: Story = {
  play: async ({ args, canvas, userEvent }) => {
    await userEvent.click(canvas.getByRole('button', { name: 'Details' }));
    await expect(args.onSelect).toHaveBeenCalledWith('42');
  },
};

En lisant de haut en bas :

  • meta décrit le composant : son nom dans la barre latérale (title), le composant concerné et les args par défaut, qui sont les props.
  • fn() crée une fonction espionne pour onSelect. Dans Storybook, chaque appel apparaît dans le panneau des actions.
  • Chaque export est une story. Default utilise les args par défaut, Selected change seulement ce qui est nécessaire, LongCustomerName teste le cas limite du nom énorme.
  • tags: ['autodocs'] génère une page de documentation avec toutes les stories et un tableau des props, tiré des types TypeScript.

Ce qui mérite une story, c'est un état, pas une variation au hasard. Pour une carte de commande : par défaut, sélectionnée, nom long, montant élevé. Pour une liste : vide et avec des éléments.

OrderList.stories.tsx
import type { Meta, StoryObj } from '@storybook/react-vite';
import { expect, fn } from 'storybook/test';
import { OrderList } from './OrderList';
 
const meta = {
  title: 'Orders/OrderList',
  component: OrderList,
  args: { selectedId: null, onSelect: fn(), orders: [] },
} satisfies Meta<typeof OrderList>;
 
export default meta;
type Story = StoryObj<typeof meta>;
 
export const Empty: Story = {
  play: async ({ canvas }) => {
    await expect(canvas.getByText('No orders here yet.')).toBeVisible();
  },
};
 
export const WithOrders: Story = {
  args: {
    selectedId: '2',
    orders: [
      { id: '1', customer: 'Ana', total: 89, status: 'paid' },
      { id: '2', customer: 'Bruno', total: 240, status: 'pending' },
      { id: '3', customer: 'Carla', total: 1320, status: 'shipped' },
    ],
  },
};

Niveau 2 : controls et documentation#

Ce niveau vient presque gratuitement. Comme les props sont dans les args, Storybook construit tout seul le panneau Controls : on peut changer le nom du client, le statut ou le montant directement à l'écran et voir le composant réagir. C'est excellent pour montrer le composant à des personnes qui ne codent pas.

Et autodocs rassemble le tout sur une page par composant. Pour un composant partagé, cette page remplace souvent un README que personne ne met à jour.

Niveau 3 : tests d'interaction#

C'est ici que Storybook cesse d'être une vitrine et devient un outil de test. La fonction play s'exécute après l'affichage de la story : elle clique, saisit et vérifie.

Revenez à la dernière story de OrderCard : ClickingDetailsSendsTheId clique sur le bouton « Details » et vérifie que onSelect a été appelé avec l'id '42'. Les composants qui ont leur propre état fonctionnent aussi :

StatusFilter.stories.tsx
import type { Meta, StoryObj } from '@storybook/react-vite';
import { useState } from 'react';
import { expect } from 'storybook/test';
import { StatusFilter, type StatusFilterValue } from './StatusFilter';
 
const meta = {
  title: 'Orders/StatusFilter',
  component: StatusFilter,
  args: { value: 'all', onChange: () => {} },
  // Keeps the value in local state so the story behaves like the real screen.
  render: function Render(args) {
    const [value, setValue] = useState<StatusFilterValue>(args.value);
    return <StatusFilter value={value} onChange={setValue} />;
  },
} satisfies Meta<typeof StatusFilter>;
 
export default meta;
type Story = StoryObj<typeof meta>;
 
export const Interactive: Story = {
  play: async ({ canvas, userEvent }) => {
    await userEvent.click(canvas.getByRole('button', { name: 'paid' }));
    await expect(canvas.getByRole('button', { name: 'paid' })).toHaveClass('active');
  },
};

Le render garde la valeur dans un useState, pour que la story se comporte comme le vrai écran, et play clique sur « paid » et vérifie que le bouton est devenu actif.

Le plus important : avec l'addon Vitest, chaque story est un test, même celles sans play. Une story qui se contente de s'afficher teste déjà que le composant ne casse pas avec ces données. Pour tout lancer :

npx vitest run --project=storybook

Dans le projet de l'article : 6 fichiers, 15 tests, tous au vert, dans un vrai Chromium, sans ouvrir de fenêtre. Et on peut lancer la même commande en CI :

.github/workflows/storybook.yml
name: Storybook tests
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: npm ci
      - run: npx playwright install --with-deps chromium
      - run: npx vitest run --project=storybook

Niveau 4 : accessibilité#

L'addon d'accessibilité lance axe, la même bibliothèque que plusieurs extensions de navigateur, sur chaque story. L'installeur le configure ainsi :

.storybook/preview.tsx
import type { Preview } from '@storybook/react-vite';
 
const preview: Preview = {
  parameters: {
    a11y: {
      // 'todo': shows violations in the UI only. 'error': fails the test.
      test: 'todo',
    },
  },
};
 
export default preview;

Avec 'todo', les problèmes apparaissent dans le panneau mais ne cassent rien. Avec 'error', ils deviennent des échecs de test. Pour vérifier, j'ai créé une story avec un bouton qui n'a qu'une icône et aucun texte. Avec 'error', le test a échoué sur la règle button-name d'axe : un bouton doit avoir un texte qu'un lecteur d'écran peut lire.

Une approche qui fonctionne bien : commencez avec 'todo', corrigez ce qui apparaît et passez à 'error' une fois que tout est propre. À partir de là, un nouveau composant avec un problème d'accessibilité ne passe plus.

Une limite importante : la vérification automatique détecte une partie des problèmes, comme l'absence de nom, le contraste et les attributs incorrects. L'ordre de lecture, le focus et la cohérence de l'expérience avec un lecteur d'écran demandent toujours des tests manuels.

Niveau 5 : tests visuels#

Les tests d'interaction vérifient le comportement. Les tests visuels vérifient l'apparence : ils prennent une capture de chaque story et la comparent à la précédente, en prévenant dès qu'un pixel a changé. C'est ce qui repère la modification CSS qui a cassé un composant sur un autre écran.

L'addon ajouté par l'installeur (@chromatic-com/storybook) relie Storybook à Chromatic, un service payant de la même équipe que Storybook. En novembre 2026, l'offre gratuite donnait 5 000 snapshots par mois, sur Chrome uniquement.

Cela vaut le coup quand beaucoup de personnes touchent aux mêmes composants, comme dans un design system. Dans une petite application, cela coûte souvent plus d'attention (relire des différences attendues) que cela n'en fait gagner.

Niveau 6 : IA#

addon-mcp relie Storybook aux assistants IA. D'après la documentation, l'agent apprend à connaître vos composants et leur documentation, génère des stories et lance les tests d'interaction et d'accessibilité pour vérifier son propre travail. La documentation prévient elle-même que ces fonctionnalités sont en preview et peuvent changer.

La vraie valeur apparaît quand le Storybook est déjà bien tenu : l'agent réutilise les composants existants au lieu d'en inventer d'autres. Dans un Storybook avec trois stories abandonnées, il n'a pas grand-chose à apprendre.

Jusqu'où aller#

Ma recommandation, par type de projet :

Jusqu'au niveau 4, cela vaut pour presque tous les projets. Au-delà, tout dépend du nombre de personnes qui utilisent les mêmes composants
  • Petite application, une ou deux personnes : niveaux 0 à 3, seulement sur les composants visuels que vous réutilisez. Le gain : développer isolément et avoir des tests d'interaction gratuitement.
  • Application d'équipe : niveaux 0 à 4, avec les tests en CI et l'accessibilité en 'error'.
  • Design system ou bibliothèque partagée : tous les niveaux. Ici, Storybook est le produit : documentation, catalogue et garantie que rien n'a changé par accident.

Et ce que je ne ferais dans aucun cas :

  • Des stories de pages entières qui récupèrent des données. Elles obligent à simuler l'API, l'authentification et les routes, et cassent à chaque changement du backend. Si l'écran a une partie visuelle importante, isolez-la dans un composant qui reçoit des props et écrivez sa story.
  • Une story pour chaque combinaison de props. Six tailles fois quatre couleurs fois deux états n'aident personne. Choisissez les états qui comptent et laissez le reste au panneau de controls.
  • Viser 100 % de couverture. La story d'un composant que personne ne réutilise ni ne modifie, c'est de la maintenance sans retour.
  • Des stories que personne ne lance. Si les stories ne sont pas en CI, elles cassent en silence et Storybook devient un musée.

Erreurs fréquentes#

  • Un composant qui récupère ses données lui-même. Il n'entre pas dans Storybook sans simuler l'API. La solution consiste presque toujours à isoler la partie visuelle, qui reçoit tout par props.
  • De gros args copiés dans chaque story. Mettez les données par défaut dans meta.args et ne changez que le nécessaire dans chaque story.
  • Des actions sans fn(). Sans fonction espionne, play ne peut pas vérifier ce qui a été appelé, et le panneau des actions reste vide.
  • Garder les exemples de l'installeur. Le bouton et la page d'exemple encombrent la barre latérale et les tests.
  • L'accessibilité toujours en 'todo'. Un avertissement qui ne devient jamais une erreur finit ignoré.

Checklist#

  • Storybook installé avec npm create storybook@latest, exemples supprimés.
  • Stories à côté des composants visuels, avec les états qui comptent (par défaut, vide, long, erreur).
  • Données par défaut dans meta.args, fonctions d'événement avec fn().
  • autodocs sur les composants partagés.
  • play sur les comportements importants (clic, saisie, sélection).
  • npx vitest run --project=storybook en CI.
  • Accessibilité en 'error' une fois le projet propre.
  • Tests visuels seulement si beaucoup de personnes touchent aux mêmes composants.
  • Aucune story de page qui dépend d'une API.

Références#

  • Front-end
  • storybook
  • react
  • tests
  • design-system
  • accessibilite

Écrit par

Ingénieure logiciel et designer. J'écris sur ce que je rencontre en créant des apps, des APIs et des produits.

Commentaires

Connectez-vous avec votre compte GitHub pour commenter.