Introduction à l'utilisation de Storybook dans un projet Vue.js

Cet article fait partie d'une série d'articles techniques qui expliqueront les défis auxquels l'équipe Front-end de Scalingo a été confrontée lors de la refonte de notre tableau de bord. Cet épisode est le premier et a été écrit par Cyrille Colon, Ingénieur Logiciel chez Scalingo, le PaaS européen.

Chez Scalingo, nous avons utilisé Storybook pendant un an pendant que nous refaisions le tableau de bord utilisé par nos clients.

Nous pensions que rédiger sur toutes nos apprises serait utile pour d'autres développeurs et c'est pourquoi nous avons écrit ce guide pour Storybook dans un projet Vue.js.

Nous allons commencer par un bref rappel sur Storybook avant d'expliquer différents cas d'utilisation. Nous terminerons l'article avec des conseils et astuces pour utiliser Storybook dans un projet Vue.js.

Prêt ? Plongeons dans le sujet !

Qu'est-ce que Storybook ?

Ceci est extrait de la page d'accueil de Storybook: Storybook est un outil open source pour développer des composants et des pages d'interface utilisateur en isolation. Il simplifie la construction, la documentation et les tests des UIs.

Pour comprendre pourquoi, commençons par un exemple très simple.

Vous souhaitez construire une application web, et cette application a besoin de boutons. Chaque application a besoin de boutons, n'est-ce pas ?

Voici un bouton "Mettre à jour" typique :

Ce bouton typique est implémenté comme un composant Vue et le code est écrit dans un fichier Button.vue.

Ce composant button peut avoir de nombreux états et être de plusieurs types.

Maintenant, les problèmes typiques auxquels chaque développeur Front-end sera confronté sont :

• sans regarder le code, comment pouvez-vous voir le bouton en action avec ses différents états et différents types ?

• comment pouvez-vous contrôler que la petite correction que vous venez d'écrire n'altérera pas le bouton dans tous les états et types ?

• comment puis-je montrer mon implémentation actuelle d'un composant à mes collègues non développeurs ?

C'est là que Storybook vous aidera.

Tout d'abord, vous écrirez une histoire, la liste des différentes instanciations d'un composant avec ses différents états et types que vous souhaitez voir dans votre Storybook. Généralement, vous souhaitez afficher une liste exhaustive de tous les états, types et propriétés de votre composant. Chez Scalingo, nous aimons appeler cela faire la storybook d'un composant.

Vous pouvez ensuite exporter le Storybook de votre projet, la liste de toutes les histoires, et l'afficher dans votre navigateur.

Voici le code de l'histoire du bouton que nous avons écrite :

import Button from "@/components/molecules/buttons/Button"; // The component I want to "storybook"

export default {
  title: "Molecules/ButtonDemo", // The story path
  component: Button, // The element the story is about
};

const Template = () => ({
  components: { Button }, // Components available in the story template, just below
  template: `
    <div class="flex space-x-3 p-2">
      <Button kind="regular">Regular</Button>
      <Button kind="primary">Primary</Button>
      <Button kind="warning">Warning</Button>
      <Button kind="danger">Danger</Button>
      <Button kind="neutral">Neutral</Button>
      <Button kind="empty">Empty</Button>
    </div>
  `, // Let's use 6 variants of my button
}); // My variable "Template" will need to be bind to value before to become a story.

export const Default = Template.bind({}); // "default" will be the story name, and so, last path element
Default.args = {}; // Story args are for latter

import Button from "@/components/molecules/buttons/Button"; // The component I want to "storybook"

export default {
  title: "Molecules/ButtonDemo", // The story path
  component: Button, // The element the story is about
};

const Template = () => ({
  components: { Button }, // Components available in the story template, just below
  template: `
    <div class="flex space-x-3 p-2">
      <Button kind="regular">Regular</Button>
      <Button kind="primary">Primary</Button>
      <Button kind="warning">Warning</Button>
      <Button kind="danger">Danger</Button>
      <Button kind="neutral">Neutral</Button>
      <Button kind="empty">Empty</Button>
    </div>
  `, // Let's use 6 variants of my button
}); // My variable "Template" will need to be bind to value before to become a story.

export const Default = Template.bind({}); // "default" will be the story name, and so, last path element
Default.args = {}; // Story args are for latter

import Button from "@/components/molecules/buttons/Button"; // The component I want to "storybook"

export default {
  title: "Molecules/ButtonDemo", // The story path
  component: Button, // The element the story is about
};

const Template = () => ({
  components: { Button }, // Components available in the story template, just below
  template: `
    <div class="flex space-x-3 p-2">
      <Button kind="regular">Regular</Button>
      <Button kind="primary">Primary</Button>
      <Button kind="warning">Warning</Button>
      <Button kind="danger">Danger</Button>
      <Button kind="neutral">Neutral</Button>
      <Button kind="empty">Empty</Button>
    </div>
  `, // Let's use 6 variants of my button
}); // My variable "Template" will need to be bind to value before to become a story.

export const Default = Template.bind({}); // "default" will be the story name, and so, last path element
Default.args = {}; // Story args are for latter

import Button from "@/components/molecules/buttons/Button"; // The component I want to "storybook"

export default {
  title: "Molecules/ButtonDemo", // The story path
  component: Button, // The element the story is about
};

const Template = () => ({
  components: { Button }, // Components available in the story template, just below
  template: `
    <div class="flex space-x-3 p-2">
      <Button kind="regular">Regular</Button>
      <Button kind="primary">Primary</Button>
      <Button kind="warning">Warning</Button>
      <Button kind="danger">Danger</Button>
      <Button kind="neutral">Neutral</Button>
      <Button kind="empty">Empty</Button>
    </div>
  `, // Let's use 6 variants of my button
}); // My variable "Template" will need to be bind to value before to become a story.

export const Default = Template.bind({}); // "default" will be the story name, and so, last path element
Default.args = {}; // Story args are for latter

➡️ Et voici ce que vous obtiendrez en exécutant Storybook dans votre navigateur :

Ce n'est pas une image rendue de votre composant, c'est une page en direct ! Vous pouvez vraiment interagir avec les différents boutons.

Les instanciations des composants vivent dans un "canvas" qui fonctionne à l'intérieur d'une boîte à outils.

Les composants à l'intérieur du canevas se comportent de manière assez proche de leur comportement réel dans l'application.

À gauche de l'image ci-dessus, vous pouvez avoir un aperçu des nombreuses histoires du projet tableau de bord chez Scalingo.

Comment pouvez-vous utiliser Storybook pour Vue.js ?

Storybook comme documentation pour les développeurs

La première utilisation évidente de Storybook est pour la documentation. Chez Scalingo, nous l'utilisons tous les jours pour notre documentation interne.

Il fait un excellent travail ici : la recherche et la structure en arborescence facilitent la recherche de ce que vous voulez ou simplement de regarder de manière exhaustive.

Étant donné sa nature auto-générée, il est toujours à jour, à aucun coût pour quiconque.

Storybook est livré avec des fonctionnalités éclatantes concernant la documentation : l'onglet docs et les panneaux de contrôle.

Bien qu'ils soient merveilleux à première vue, nous n'avons pas trouvé d'utilisation pratique pour les panneaux de contrôle. Nous avons fini par n'utiliser que l'onglet docs pour localiser le composant/arguments d'histoire visibles dans le canevas.

Storybook comme simulateurs d'états

Une autre utilisation de Storybook dans Vue.js est de l'utiliser comme simulateurs d'états.

Imaginons que vous ayez un tableau.

Le tableau peut avoir plusieurs états par lui-même (initial, vide, quelques éléments, paginés) et chaque ligne peut avoir des états supplémentaires (par exemple, si le tableau contient des "messages", ils peuvent être "envoyés", "retardés", "brouillon", ...). Certains de ces états sont mutuellement exclusifs.

Storybook vous permet de les voir tous, au coût d'un seul clic (ou moins, si vous les regroupez dans une seule histoire).

Storybook comme outil de communication

Une autre utilisation de Storybook peut être de l'utiliser comme outil de communication. Cela sera particulièrement utile pour les responsables de produit.

Un storybook peut être exporté en tant que site web statique avec une simple commande :

À partir de là, il peut être entièrement utilisé par différentes personnes "prêt à l'emploi". Pas d'API nécessaire. Plus besoin de yarn & co.

Les responsables de produit peuvent facilement naviguer vers une fonctionnalité d'application et voir tous les états associés. Ils peuvent également copier-coller des liens (URLs des histoires de storybook) et/ou annoter des captures d'écran.

C'est très utile pour ouvrir un problème et le rendre très descriptif avec l'intention du responsable produit.

Par exemple, nous avons dû demander conseil à un designer externe qui n'était pas familier avec le projet. En quelques minutes, la personne a pu saisir notre problème et proposer des solutions en manipulant tous les états du composant.

Storybook comme source de tests visuels automatisés

Via certains outils, il est possible d'ajouter une automatisation à un storybook. Si vous avez fait des tests visuels dans le passé, vous vous souvenez peut-être que cela peut être assez douloureux.

Les tests visuels sont souvent très lents, mais le pire problème est "flake".

Les tests instables sont des tests qui passent parfois, parfois non, de manière plus ou moins aléatoire.

Chez Scalingo, nous utilisons Loki.

Storybook et Loki fonctionnent très bien ensemble : le nombre de cas de flake que nous avions est nul, même avec des animations CSS dans certaines histoires.

Loki/Storybook est également assez rapide (200 histoires prennent 60 secondes) et le mécanisme de différence de Loki facilite l'identification de ce qui a mal tourné.

Dans l'exemple ci-dessous, j'ai élargi le cercle. Loki a détecté la différence visuelle et le test d'histoire associé a échoué.

Et voici l'image de différence résultante produite par Loki. Les différences apparaissent en rose.

Du côté de la maintenance, étant donné que vous pouvez facilement passer en revue les différences via des images et accepter un nouvel état de référence via une seule ligne de commande, c'est un vrai bonheur.

Les tests visuels nous permettent vraiment d'être confiants lors des mises en production ou des mises à jour de dépendances.

Idéalement, vous souhaitez que vos tests visuels soient automatisés dans votre CI.

Les créateurs de Storybook ont créé Chromatic pour cela. Non seulement il exécute les tests CI, mais il possède également des fonctionnalités telles que servir des storybooks ou des collaborations PR.

Nous n'avons fini par ne pas l'utiliser uniquement à cause de son prix. Dans notre cas, cela aurait coûté plus de 2500 euros par développeur chaque année - uniquement pour une couverture Chrome.

Si vous souhaitez une couverture plus complète (3 navigateurs, 4 modes de réactivité, 2 thèmes), le prix augmente rapidement.

Loki a une intégration CI, mais à des années-lumière de Chromatic (pas de tableau de bord pour explorer les résultats de construction, configuration manuelle, ...).

Pour l'instant, nous exécutons simplement Loki manuellement avant la mise en production - ou à des moments particuliers (comme une mise à jour des dépendances). Ensuite, nous poussons les images dans une demande PR et utilisons les outils de comparaison de Github (côté à côté, glissement, peau d'oignon) pour observer les différences.

Cela fonctionne bien, même si ce n'est pas - bien sûr - parfait.

Storybook comme visualiseurs de variantes

Les cibles des applications Web sont maintenant plus larges que jamais : très grands écrans, mobiles, navigateurs, mode sombre, ...

Le canevas de Storybook peut afficher des composants sous différentes variantes, via des paramètres.

Prêt à l'emploi, vous aurez la capacité de changer la taille de l'écran du canevas, mais vous pouvez également coder des paramètres personnalisés.

Chez Scalingo, nous avons ajouté deux variantes pour gérer l'i18n et le thème.

Astuces et conseils issus de notre expérience avec Storybook pour Vue.js chez Scalingo !

Utilisez le format js, pas mdx

Storybook propose deux formats d'histoires : js et mdx (mdx sont des fichiers md, avec la possibilité d'avoir des sections js). Nous avons initialement choisi le format mdx pour ses capacités de documentation améliorées. Il s'est avéré que c'était une mauvaise idée.

En effet, nous n'avons pas utilisé les fonctionnalités supplémentaires de mdx et la maintenance avec mdx est particulièrement plus difficile.

Il était préférable d'avoir des fichiers md séparés pour les quelques points que nous souhaitions documenter et d'utiliser le format js "plus standard". La raison est qu'en particulier avec Vue.js, vous aurez moins de bogues et plus de documentation en ligne avec le format js.

VueDevTools dans Storybook

Les VueDevTools ne fonctionnent pas en mode canevas mais fonctionnent si le canevas est ouvert dans un nouvel onglet (deuxième icône en haut à gauche).

Séparer les préoccupations de vos composants (Contrôleur/Vues...)

Nous avons fait le choix de séparer les préoccupations de nos composants.

Concrètement, nous avons trois types de composants : contrôleurs, vues, système de design. Les composants contrôleurs sont les seuls autorisés à interagir avec le modèle (services, magasin). Cela nous permet d'avoir tous les autres composants comme des composants visuels "purs", drivés uniquement par des propriétés "stupides".

Cela mène à une création/mise à jour facile de composants de vue complexes, via de simples fichiers json plats.

import Projects from "@/components/views/Projects";
import currentUser from "@/stories/data/currentUser.json";
import props from "./props.json";

export default {
  title: "Views/Main/Apps",
  component: Projects,
};

const Template = (args, { argTypes }) => ({
  props: Object.keys(argTypes),
  components: { Projects },
  template: `<Projects v-bind="$props">`,
});

export const Default = Template.bind({});
Default.args = {
  user: currentUser,
  ...props,
};

import Projects from "@/components/views/Projects";
import currentUser from "@/stories/data/currentUser.json";
import props from "./props.json";

export default {
  title: "Views/Main/Apps",
  component: Projects,
};

const Template = (args, { argTypes }) => ({
  props: Object.keys(argTypes),
  components: { Projects },
  template: `<Projects v-bind="$props">`,
});

export const Default = Template.bind({});
Default.args = {
  user: currentUser,
  ...props,
};

import Projects from "@/components/views/Projects";
import currentUser from "@/stories/data/currentUser.json";
import props from "./props.json";

export default {
  title: "Views/Main/Apps",
  component: Projects,
};

const Template = (args, { argTypes }) => ({
  props: Object.keys(argTypes),
  components: { Projects },
  template: `<Projects v-bind="$props">`,
});

export const Default = Template.bind({});
Default.args = {
  user: currentUser,
  ...props,
};

import Projects from "@/components/views/Projects";
import currentUser from "@/stories/data/currentUser.json";
import props from "./props.json";

export default {
  title: "Views/Main/Apps",
  component: Projects,
};

const Template = (args, { argTypes }) => ({
  props: Object.keys(argTypes),
  components: { Projects },
  template: `<Projects v-bind="$props">`,
});

export const Default = Template.bind({});
Default.args = {
  user: currentUser,
  ...props,
};

Si votre composant est déjà fonctionnel dans un navigateur, vous pouvez utiliser l'onglet VueDevTools/composant pour copier les propriétés et les coller dans le fichier json.

Ajoutez StoriesWrapper autour de vos histoires

Il existe au moins deux raisons différentes d'ajouter un conteneur autour de vos histoires.

Dans notre cas, nous utilisons le routage imbriqué. Donc, le composant de vue final est, dans l'application réelle, enveloppé autour de N composants. Si vous avez un routeur, la vue est au moins enveloppée dans le composant App. Le wrapper d'histoires est là pour reproduire cet environnement "enveloppé".

La deuxième raison : le wrapper peut également vous aider à contrôler finement les paramètres du canevas.

Voici notre configuration preview.js, avec nos deux menus de barre d'outils supplémentaires "i18n" et "thème"

// config/storybook/preview.js
export const globalTypes = {
  language: {
    name: "i18n",
    description: "i18n selector",
    defaultValue: "en",
    toolbar: {
      items: ["en", "fr"],
    },
  },
  theme: {
    name: "theme",
    description: "theme selector",
    defaultValue: "light",
    toolbar: {
      items: ["light", "dark"],
    },
  },
};

const appSbProvider = (Story, context) => ({
  template: "<story/>",
  data() {
    return { theme: context.globals.theme, language: context.globals.language };
  },
});

export const decorators = [appSbProvider];

// config/storybook/preview.js
export const globalTypes = {
  language: {
    name: "i18n",
    description: "i18n selector",
    defaultValue: "en",
    toolbar: {
      items: ["en", "fr"],
    },
  },
  theme: {
    name: "theme",
    description: "theme selector",
    defaultValue: "light",
    toolbar: {
      items: ["light", "dark"],
    },
  },
};

const appSbProvider = (Story, context) => ({
  template: "<story/>",
  data() {
    return { theme: context.globals.theme, language: context.globals.language };
  },
});

export const decorators = [appSbProvider];

// config/storybook/preview.js
export const globalTypes = {
  language: {
    name: "i18n",
    description: "i18n selector",
    defaultValue: "en",
    toolbar: {
      items: ["en", "fr"],
    },
  },
  theme: {
    name: "theme",
    description: "theme selector",
    defaultValue: "light",
    toolbar: {
      items: ["light", "dark"],
    },
  },
};

const appSbProvider = (Story, context) => ({
  template: "<story/>",
  data() {
    return { theme: context.globals.theme, language: context.globals.language };
  },
});

export const decorators = [appSbProvider];

// config/storybook/preview.js
export const globalTypes = {
  language: {
    name: "i18n",
    description: "i18n selector",
    defaultValue: "en",
    toolbar: {
      items: ["en", "fr"],
    },
  },
  theme: {
    name: "theme",
    description: "theme selector",
    defaultValue: "light",
    toolbar: {
      items: ["light", "dark"],
    },
  },
};

const appSbProvider = (Story, context) => ({
  template: "<story/>",
  data() {
    return { theme: context.globals.theme, language: context.globals.language };
  },
});

export const decorators = [appSbProvider];

Et comment nous l'utilisons dans notre enfant appelé dans tous nos wrappers d'histoires

// src/components/others/storybook/AppSb.vue
export default {
  name: "AppSb",
  ...
  created() {
    this.changeLanguage(this.$root.$children[0].language);
    this.changeTheme(this.$root.$children[0].theme);
  },
  ...
};

// src/components/others/storybook/AppSb.vue
export default {
  name: "AppSb",
  ...
  created() {
    this.changeLanguage(this.$root.$children[0].language);
    this.changeTheme(this.$root.$children[0].theme);
  },
  ...
};

// src/components/others/storybook/AppSb.vue
export default {
  name: "AppSb",
  ...
  created() {
    this.changeLanguage(this.$root.$children[0].language);
    this.changeTheme(this.$root.$children[0].theme);
  },
  ...
};

// src/components/others/storybook/AppSb.vue
export default {
  name: "AppSb",
  ...
  created() {
    this.changeLanguage(this.$root.$children[0].language);
    this.changeTheme(this.$root.$children[0].theme);
  },
  ...
};

Cela nous permet de monter des histoires de vues "comme une application", sans trop d'effort. Et de les contrôler via la barre d'outils Storybook.

// The Storybook wrapper
import WelcomeSb from "@/components/others/storybook/WelcomeSb";
// The component we want to storify
import Projects from "@/components/views/Projects";

// Flat Props in json files
import currentUser from "@/stories/data/currentUser.json";
import props from "./props.json";

export default {
  title: "Views/Main/Apps",
  component: Projects,
};

const Template = (args, { argTypes }) => ({
  props: Object.keys(argTypes),
  components: { Projects, WelcomeSb },
  template: `<WelcomeSb selectedRoute="Projects"><Projects v-bind="$props"></Projects></WelcomeSb>`,
});

export const Default = Template.bind({});
Default.args = {
  user: currentUser,
  ...props,
};

// The Storybook wrapper
import WelcomeSb from "@/components/others/storybook/WelcomeSb";
// The component we want to storify
import Projects from "@/components/views/Projects";

// Flat Props in json files
import currentUser from "@/stories/data/currentUser.json";
import props from "./props.json";

export default {
  title: "Views/Main/Apps",
  component: Projects,
};

const Template = (args, { argTypes }) => ({
  props: Object.keys(argTypes),
  components: { Projects, WelcomeSb },
  template: `<WelcomeSb selectedRoute="Projects"><Projects v-bind="$props"></Projects></WelcomeSb>`,
});

export const Default = Template.bind({});
Default.args = {
  user: currentUser,
  ...props,
};

// The Storybook wrapper
import WelcomeSb from "@/components/others/storybook/WelcomeSb";
// The component we want to storify
import Projects from "@/components/views/Projects";

// Flat Props in json files
import currentUser from "@/stories/data/currentUser.json";
import props from "./props.json";

export default {
  title: "Views/Main/Apps",
  component: Projects,
};

const Template = (args, { argTypes }) => ({
  props: Object.keys(argTypes),
  components: { Projects, WelcomeSb },
  template: `<WelcomeSb selectedRoute="Projects"><Projects v-bind="$props"></Projects></WelcomeSb>`,
});

export const Default = Template.bind({});
Default.args = {
  user: currentUser,
  ...props,
};

// The Storybook wrapper
import WelcomeSb from "@/components/others/storybook/WelcomeSb";
// The component we want to storify
import Projects from "@/components/views/Projects";

// Flat Props in json files
import currentUser from "@/stories/data/currentUser.json";
import props from "./props.json";

export default {
  title: "Views/Main/Apps",
  component: Projects,
};

const Template = (args, { argTypes }) => ({
  props: Object.keys(argTypes),
  components: { Projects, WelcomeSb },
  template: `<WelcomeSb selectedRoute="Projects"><Projects v-bind="$props"></Projects></WelcomeSb>`,
});

export const Default = Template.bind({});
Default.args = {
  user: currentUser,
  ...props,
};

Inconvénients de Storybook

Bien sûr, nous voulons être entièrement transparents sur notre utilisation de Storybook. Cela peut aussi avoir ses moments douloureux.

La création de configuration et l'édition de configuration peuvent être un cauchemar (en raison d'une complexité élevée et d'une documentation médiocre) et chaque mise à jour de version peut rapidement vous coûter des heures. Peut-être est-ce parce que nous utilisons Vue.js, qui n'est pas un framework de premier plan.

Il sera difficile de préciser exactement combien Storybook coûte en "temps inutile", mais d'après notre expérience, nous dirions environ 4 heures par mois, principalement lors des mises à jour de versions cassées.

Cela ne tient pas compte du temps passé à mettre à jour les histoires lorsque les spécifications de l'application ont changé. Comme tous les tests, les coûts varieront en fonction de l'étendue de la couverture. Cependant, nous dirions que comparativement à d'autres types de tests, les histoires sont facilement mises à jour.

Conclusion

Chaque fois que nous voulons utiliser un outil chez Scalingo, nous devons nous poser deux questions :

• Pouvons-nous nous permettre le coût de maintenance ?

• Le retour sur investissement (ROI) en vaut-il la peine ?

En fin de compte, en plus d'être précieux lors des phases de développement, Storybook résout 50 % du problème des tests visuels pour un faible coût de maintenance (temps de développement dépensé).

Storybook facilite également la collaboration avec des coéquipiers non codeurs ou même des utilisateurs finaux.

Nous sommes très heureux avec Storybook et le recommanderions.

Si vous utilisez Storybook, faites-nous savoir ce que vous en pensez en commentant cet article !