Dépendances homologues et élimination des branches mortes

Les dépendances entre pairs déclarent les paquets dont votre bibliothèque a besoin, mais qu’elle attend de l’utilisateur. Dans le package.json de votre bibliothèque, React doit figurer dans peerDependencies, et non dans dependencies. Lorsqu’une personne installe votre bibliothèque, npm/yarn n’installe pas React automatiquement : l’application de cette personne possède déjà React et votre bibliothèque partage cette instance.

Si React figure dans les dependencies de votre bibliothèque, npm peut installer une deuxième copie de React à côté de celle de l’utilisateur. Deux instances de React dans la même application cassent tous les points d’ancrage avec l’erreur « Invalid hook call ». En déclarant React comme peerDependency, vous indiquez à npm : « J’ai besoin de React, mais utilisez celui que l’utilisateur possède déjà. »

Certaines dépendances entre pairs peuvent être facultatives — par exemple une bibliothèque qui prend en charge à la fois styled-components et CSS Modules. Marquez les dépendances entre pairs facultatives à l’aide de peerDependenciesMeta : { 'styled-components': { optional: true } }. npm n’avertira pas les utilisateurs si des dépendances facultatives sont absentes, mais les types TypeScript peuvent tout de même être fournis lorsque le paquet facultatif est installé.

Le champ sideEffects de package.json indique aux outils de regroupement si votre bibliothèque peut être entièrement soumise à l’élimination du code inutilisé. Définir "sideEffects": false indique à webpack, Rollup et aux outils similaires que l’importation de n’importe quel module de votre bibliothèque ne provoque aucun effet de bord : toutes les exportations inutilisées peuvent être éliminées sans risque du paquet de l’utilisateur.

Les importations CSS sont un effet de bord courant : elles injectent des styles dans la page du simple fait de leur importation. Si votre bibliothèque importe des fichiers CSS, définissez "sideEffects": ["*.css", "*.scss"] pour indiquer aux outils de regroupement que les fichiers JS peuvent être soumis à l’élimination du code inutilisé, mais que les fichiers CSS doivent toujours être inclus lorsqu’ils sont importés.

Pour maximiser l’élimination du code inutilisé, exportez chaque composant en tant qu’exportation nommée depuis son propre fichier. Dans votre index.ts, réexportez tout : export { Button } from './Button'. Lorsqu’un utilisateur importe uniquement Button, l’outil de regroupement peut éliminer tous les autres composants. Les fichiers d’agrégation contenant des réexportations permettent ce modèle.

Utilisez bundlejs.com pour vérifier l’élimination du code inutilisé : collez votre instruction d’importation et le site indique la taille réelle du paquet. Le paquet npm size-limit vous permet de définir des budgets de taille dans votre package.json et d’échouer dans l’intégration continue si la taille de l’importation dépasse la limite : "size-limit": [{ "path": "dist/index.js", "limit": "10 KB" }].

Définissez un budget de taille pour les importations de votre bibliothèque. Exécutez npx size-limit dans l’intégration continue pour le faire respecter. Une augmentation progressive de l’impact du paquet indique un élargissement du périmètre. Une bibliothèque de composants ciblée devrait maintenir les importations de chaque composant en dessous de quelques kilo-octets. Alertez en cas de régression avant qu’elle n’atteigne les utilisateurs.

Évitez styled-components et Emotion dans les bibliothèques de composants que vous prévoyez de distribuer. Ces solutions d’injection de CSS à l’exécution obligent l’utilisateur à installer la même bibliothèque dans la même version, ce qui crée des conflits de dépendances entre pairs. Même si l’utilisateur utilise Tailwind ou du CSS simple, il doit tout de même regrouper le moteur d’exécution de CSS dans JS. Préférez les modules CSS, qui sont compilés en CSS simple au moment de la compilation.

Les modules CSS fonctionnent bien dans les bibliothèques lorsqu’ils sont associés à un outil de regroupement qui les traite. tsup et Rollup peuvent incorporer la sortie des modules CSS sous forme de noms de classe limités à une portée. L’utilisateur n’a rien à configurer : les styles sont déjà limités à une portée et inclus dans le paquet JS ou dans un fichier CSS séparé qui est importé.

Vos propres outils de développement (tsup, TypeScript, bibliothèques de vérification, Storybook) vont dans devDependencies : ils ne sont nécessaires que pendant le développement et ne sont pas installés chez les utilisateurs par npm. React va à la fois dans peerDependencies (exigence d’exécution) et dans devDependencies (nécessaire pour compiler et vérifier votre bibliothèque localement).

Que communique aux outils de regroupement la définition de "sideEffects": false dans le package.json d’une bibliothèque ?

Déclarez React dans peerDependencies (et non dans dependencies) afin que les utilisateurs partagent l’instance de React de leur application. sideEffects: false permet l’élimination complète du code inutilisé de votre bibliothèque. Utilisez sideEffects: ['*.css'] pour empêcher la suppression des importations CSS. Les exportations nommées depuis des fichiers individuels maximisent la granularité de l’élimination du code inutilisé. Imposez un budget de taille avec size-limit dans l’intégration continue. Préférez les modules CSS au CSS dans JS dans les bibliothèques afin d’éviter les conflits de dépendances entre pairs.