Créer des web components avec TypeScript
Ces derniers mois, j’ai cherché comment mêler deux de mes « technologies » préférées du moment : les web components et TypeScript.
Je comprends les web components tels qu’ils sont décrits sur leur page MDN :
Les Web Components sont un ensemble de technologies différentes qui permettent de créer des éléments personnalisés réutilisables, dont la fonctionnalité est encapsulée à l’écart du reste de votre code, et de les utiliser dans vos applications web.
Donc, à mon avis, ils ne vont pas remplacer des frameworks comme React ou Angular, mais ils sont un moyen de créer des morceaux de code réutilisables que vous pouvez utiliser quelle que soit votre pile front-end.
D’un autre côté, je suis tombé amoureux de TypeScript dès que j’ai commencé à l’utiliser. La possibilité d’utiliser le JavaScript le plus récent, avec la sécurité et la prévention des bogues qu’apporte le typage, est quelque chose qui me manque quand je dois travailler sur un projet qui n’en a pas.
Vous allez donc me dire que c’est facile : commencez à écrire vos composants en TypeScript, puis transpilez-les et servez-les…
et c’est ainsi que mon projet a commencé…
Rapidement, dans mon projet, j’ai voulu un moyen de servir mon composant sous la forme d’un seul fichier, tout en séparant le HTML et le CSS dans des fichiers différents pendant le développement, ou d’utiliser lit-html pour les gabarits, avec le rechargement à chaud en développement et une option pour tout empaqueter pour la production… j’ai donc commencé à expérimenter avec webpack (que j’ai remplacé plus tard par Rollup). Je voulais aussi un moyen de faire des tests, et j’ai fini par utiliser Karma et Jasmine. Je voulais un moyen d’avoir une galerie de composants, alors j’ai intégré Storybook. À la fin, je voulais publier les composants obtenus sur npm, et j’ai donc dû créer un package.json et un README.
Tout cela est inclus d’office dans ce que j’ai appelé « wc-base-typescript » (original, je sais :)).
Ce projet vous permet de commencer à écrire vos web components en TypeScript en une minute (selon votre connexion Internet) et de disposer de toutes les fonctionnalités décrites ci-dessus.
Vous voulez le tester ou l’utiliser dans vos prochains projets de web components ? Continuez à lire, ou allez directement sur le dépôt GitHub de wc-base-typescript, qui est à peu près la même chose avec moins de mots.
Bien sûr, n’oubliez pas de mettre une étoile au projet sur GitHub si vous pensez qu’il le mérite !
Et si vous pensez que quelque chose peut être fait d’une autre manière (ou mieux), n’hésitez pas à me le dire dans les commentaires ou à m’envoyer une PR, toute collaboration est la bienvenue :)
Prêt ? C’est parti !
Pour commencer
Première chose. Il vaut mieux copier le dépôt et créer le vôtre pour votre projet. Vous pouvez toujours télécharger le code, mais je recommande d’utiliser degit ou un outil similaire pour plus de commodité.
npm install -g degit #In case you don't have it installed
degit tx2z/wc-base-typescript
Une fois le projet sur votre ordinateur, entrez dans le dossier et installez toutes les dépendances npm :
npm i
Et vous pouvez commencer à écrire vos composants ! Je vous avais dit 1 minute :)
Tous les composants que vous allez créer seront stockés dans src/components.
J’ai créé dans le projet trois composants pour montrer les différentes options disponibles :
Le base-component génère un web component sans dépendance ni bibliothèque.
Le lithtml-component génère un web component qui utilise lit-html comme bibliothèque de gabarits.
Le noshadow-component génère un élément personnalisé (je ne suis pas sûr qu’on puisse l’appeler web component) sans utiliser le shadow DOM, et sans dépendance ni bibliothèque.
Pour un démarrage rapide, vous pouvez copier le contenu de l’un des composants d’exemple et modifier ce dont vous avez besoin.
Il est aussi important d’inclure votre élément personnalisé dans public/index.html pour pouvoir le tester pendant le développement. Si vous l’ouvrez, vous verrez que j’y ai inclus les trois composants d’exemple.
Ensuite, pour lancer un serveur en mode développement, il suffit de taper dans votre terminal :
npm start
Rollup va transpiler et empaqueter vos composants et recharger la page à chaque fois que vous enregistrez un fichier.
C’est tout. Rien à configurer ni à faire d’autre que vous concentrer sur votre code !
Tests
Vous voudrez peut-être ajouter quelques tests à vos composants pour éviter les problèmes quand la base de code commencera à grossir… ou, mieux encore, vous êtes un super-développeur qui aime écrire son code en suivant le processus de développement piloté par les tests (TDD).
J’ai eu du mal à ajouter des tests dans mes précédents projets de web components, mais, là encore, tout est maintenant préconfiguré et fonctionne d’emblée. Karma et Jasmine sont inclus comme environnement et framework de test.
Dans le dossier de votre composant, ajoutez un fichier se terminant par « spec.ts » et écrivez vos tests (en TypeScript). Bien sûr, il y a quelques exemples dans les composants d’exemple.
Par défaut, les lanceurs pour Chrome et Firefox sont déjà installés et configurés (vos tests seront lancés dans les deux navigateurs), mais vous pouvez installer et utiliser n’importe quel autre karma-launcher si vous le souhaitez.
Pour exécuter les tests, utilisez :
npm test
Karma a aussi le rechargement en direct : si vous modifiez vos composants ou vos fichiers de test, les tests sont de nouveau exécutés.
Utiliser Storybook comme galerie de composants
Vous pouvez éventuellement utiliser Storybook pour développer, documenter et créer une galerie pour vos web components. Vous pouvez en apprendre plus sur Storybook sur leur site de documentation.
Un petit avertissement ici : Storybook utilise webpack et, au moment de construire, c’est Rollup qui sera utilisé… le résultat devrait avoir le même aspect et le même comportement, sans être strictement identique.
Storybook pour HTML est utilisé et réglé de façon à ne demander aucune configuration supplémentaire pour vos composants. Les addons Storybook suivants sont inclus :
Knobs : permet de modifier dynamiquement les props des web components depuis l’interface de Storybook.
Viewport : permet d’afficher les web components dans Storybook avec différentes tailles et dispositions. Cela aide à construire des web components responsives dans Storybook.
A11y : aide à rendre vos web components plus accessibles.
Notes : permet d’écrire des notes ou de la documentation pour vos web components.
Il s’agit d’une installation standard de Storybook. Vous pouvez ajouter d’autres addons ou configurations adaptés à vos besoins.
Créer des stories
Deux fichiers des composants d’exemple sont utilisés par Storybook.
@component.stories.ts : c’est le fichier qui crée une story pour votre composant. Vous pouvez consulter la documentation de Storybook sur la création de stories à partir de cette page
README.md : il sert à ajouter la documentation de votre composant avec l’addon Storybook Notes.
Storybook utilisera ces deux fichiers pour générer les stories et la documentation. Une fois ces deux fichiers en place, lancez Storybook avec :
npm run storybook
Là encore, vous trouverez des exemples de tout cela dans les composants d’exemple fournis :)
Pour construire une application Storybook statique prête à être déployée, lancez :
npm run storybook-build
Vous trouverez vos builds Storybook dans le dossier « dist-storybook ».
Si vous voulez publier votre Storybook sur GitHub Pages, je vous recommande d’installer storybook-deployer. Il fera tout le travail à votre place.
Notez que Storybook est entièrement optionnel. Si vous ne l’utilisez pas, vous pouvez supprimer (ou ne pas créer) les fichiers @component.stories.ts. Vous pouvez même supprimer toutes les références à Storybook et à webpack dans le package.json pour retirer complètement Storybook de votre projet.
Construire les composants
Il est donc temps de construire vos composants pour les utiliser ailleurs. N’ayez crainte, lancez simplement :
npm run build
Vous trouverez vos builds dans le dossier « dist ».
Vos composants seront compilés en fichier JS (en module ES), pour les utiliser comme modules dans votre application, et en dist.js (en iife), pour les utiliser directement dans les navigateurs, avec le nom que vous donnez au dossier dans src/components.
Tous les modules incluront leurs fichiers de déclaration TypeScript au cas où vous ou d’autres voudriez les utiliser avec TypeScript.
Les polyfills des webcomponents seront aussi inclus dans le dossier « dist ». Vous pouvez les utiliser ou charger directement le code depuis un CDN comme unpkg : https://unpkg.com/@webcomponents/webcomponentsjs@^2/
Voilà, prenez vos composants et utilisez-les comme vous voulez. Il suffit de copier-coller la version (module ES ou IIFE) dont vous avez besoin dans votre projet et de l’utiliser.
…
Non, ce n’est pas ainsi que les choses fonctionnent de nos jours, je sais. Le wc-base-typescript simplifie aussi tout ce dont vous avez besoin pour…
Publier un composant sur NPM
Vous avez peut-être remarqué qu’un README et un « package.json » sont aussi inclus dans le dossier de chaque composant d’exemple. Rollup copiera ces fichiers dans le dossier « dist » et ajoutera des informations importantes au package.json.
En d’autres termes, vous n’avez pas à vous soucier des propriétés main, module ou type, car elles seront remplies automatiquement, mais vous devez fournir le reste des informations dans le package.json.
Pour publier votre composant sur NPM, il vous suffit d’entrer dans le dossier du composant à l’intérieur de « dist » dans votre terminal et de lancer :
npm publish
Bien sûr, vous devez avoir un compte npm et y être connecté dans votre terminal avant cela. Je recommande de lire le how-to de la documentation npm avant de publier un paquet.
Une fois votre paquet sur npm, il peut être installé et utilisé comme n’importe quel autre paquet npm. La version module ES sera celle par défaut.
Pour conclure
Avec le projet wc-base-typescript, vous pouvez donc créer, tester, construire pour la production et publier rapidement des web components, et éventuellement créer une galerie de composants pour les présenter.
Si vous voulez voir l’un des usages que j’en fais, vous pouvez consulter mon générateur de licence Creative Commons sous forme de web component, avec sa galerie et son dépôt. Je l’ai créé (tout compris) en environ 6 heures de travail intermittent.
Qu’en pensez-vous ? Peut-il vous être utile ?
PS : n’hésitez pas à me dire si vous l’utilisez dans l’un de vos projets, j’aimerais beaucoup savoir ce que vous créez avec :) P.-P.-S. : et encore une fois, si vous pensez que quelque chose peut être fait d’une autre manière (ou mieux), n’hésitez pas à me le dire dans les commentaires ou à m’envoyer une PR :D