Jouer avec npm

Le registre npm (npmjs.com) est l’hébergement principal des modules ECMAScript, pour Node et le front-end.

La commande npm install s’utilise directement quand nous connaissons déjà le nom d’un module à installer, par exemple cowsay (npmjs.com/cowsay) :

Le module est installé et prêt à être inclus dans un script. Nous constatons aussi que le champ dependencies est apparu dans le fichier package.json :

L’exécutable npm tient les comptes des modules installés à notre demande. Cela nous sera utile pour installer les modules sur un autre ordinateur. Nous reviendrons plus tard sur la notation des versions – on en reparlera sous le nom de versions sémantiques (Semantic Versionning).

L’inclusion d’un module npm est identique à celle d’un module de base.

Regardons le résultat sans plus tarder :

Le module npm nous a permis d’utiliser du code sans avoir à le créer, alors qu’il n’était pas fourni par la plate-forme Node.

Maintenant que nous savons installer un module npm, nous pouvons en chercher d’autres et comprendre comment les utiliser.

Le registre npm (npmjs.com) fourmille de modules – de simples fonctions, des bibliothèques ou des frameworks complets. Ils couvrent un spectre d’usages très larges : accès aux bases de données, frameworks web, outils front-end, utilitaires de test, compression de données, paiement bancaire, des frameworks mobiles, etc.

Cherchons une bibliothèque pour nous connecter à une base de données MySQL ou MariaDB. Tapez “mysql” dans le champ de recherche du registre npm ou saisissez directement l’URL menant aux résultats de cette recherche (npmjs.com/search?q=mysql) :

Les résultats sont triés par pertinence – un mélange entre popularité, qualité et maintenance des projets.

Je trouve qu’il est difficile de décider uniquement en regardant la liste. J’ai tendance à ouvrir un onglet par module pour en lire la documentation. Prenons le cas du module mysql2 (npmjs.com/mysql2) justement :

Plusieurs éléments de cette page tendent à me rassurer et m’aident à juger de la robustesse de ce module :

J’ai un doute quand je lis 108 issues et 13 pull requests. Dans ce cas-là, je me dis que les personnes qui maintiennent le projet ne sont pas forcément très réactives.

Cependant, il y a suffisamment d’indicateurs au vert pour l’installer avec npm install mysql2 puis l’essayer dans un script.

Le module mysql-libmysqlclient (npmjs.com/mysql-libmysqlclient) ne me fait pas du tout le même effet.

La page du module ne met pas d’exemple simple à comprendre et fait référence à des versions de Node antédiluviennes. Rien n’indique qu’il ne peut pas fonctionner avec Node v10, mais la présence du mot binding m’évoque que l’installation du module compile un programme écrit dans un autre langage – en l’occurrence, libmysqlclient.

Point positif : il n’y a que 14 issues GitHub. C’est peu, mais l’une d’entre elles est intitulée Does not work with any modern version of Node.js. Cela confirme mes doutes ; c’est suffisant pour que je passe mon chemin.

En continuant plus loin dans la liste des résultats de recherche, je suis tombé sur le module nommé falchion.

Il n’y a qu’une seule version du module, qui date de quatre années avec une documentation qui tient sur une ligne. Il y a très peu de chances que nous puissions en faire quelque chose.

Voici au final ce que j’estime être le plus important pour me faire une idée d’un module et décider de l’installer ou non :

Ce sont des critères subjectifs. Un module est parfois populaire par ancienneté alors qu’il existe des alternatives, plus légères ou plus simples d’utilisation. C’est le cas du module moment.js, plus populaire que date-fns – que je préfère.

Il y a aussi des modules dans lesquels j’ai une confiance quasi-aveugle. Ils sont publiés par les personnes présentes dans cette liste non exhaustive :

L’utilisation de la commande npm uninstall supprime en toute sécurité un module npm et les fichiers qu’il a installés. La commande le retire ensuite de la liste des dépendances du fichier package.json.

Le module cowsay n’est plus installé. Que se passe-t-il si nous exécutons à nouveau un l’exemple cow.js ?

Le chargement du module a échoué car Node n’arrive pas à le trouver – et c’est normal.

Nous devons relancer la commande npm install cowsay pour que le script fonctionne à nouveau.

Jusqu’à présent, nous avons installé des modules en les ajoutant un par un. La procédure est légèrement différente quand nous installons le projet de zéro ou quand le fichier package.json a été mis à jour par un·e collègue, par exemple.

L’exemple suivant illustre la remise à zéro des modules utilisés en exemple de ce chapitre :

Nous nous sommes positionnés dans un répertoire qui contient un fichier package.json puis nous avons supprimé tout ce qui aurait pu être installé.

La commande npm install s’utilise de manière systématique quand nous récupérons du code avec Git pour la première fois (git clone) ou après une mise à jour, par exemple avec git pull.

L’exécutable npm vérifie que la correspondance est bien respectée entre ce qui est installé dans le répertoire node_modules et les modules listés dans le fichier package.json. La commande npm install installe, met à jour et retire les modules nécessaires.

Par défaut, l’exécutable npm installe la dernière version d’un module. Nous avons la liberté d’en installer d’autres qui sont antérieures. C’est pratique quand des modules arrêtent de prendre en charge des navigateurs web ou des versions de Node alors que nous les utilisons encore.

Nous allons nous servir du module lodash (npmjs.com/lodash) pour illustrer nos allées et venues entre différentes versions. À l’heure où j’écris ces lignes, sa version la plus récente est la 4.17.11. C’est ce que rapporte le résultat de la commande npm install lodash :

L’utilisation du caractère @ conjointement à un numéro de version précise la version à installer :

Nous avons installé une version précise, mais il y a sûrement des mises à jour qui ont suivi pour corriger des bogues. Le problème est que, à ce stade, nous ne connaissons pas le numéro de version à spécifier. Idéalement, je préférerais installer la version la plus récente de la série 3. Il se trouve que l’exécutable npm sait le faire pour nous et sans effort :

Nous pouvons faire la même chose avec les versions les plus récentes de la série 3 et de la série 2.2 :

Revenons à la version la plus récente en réutilisant la commande d’installation abordée auparavant :

Quelque chose d’inattendu s’est produit : la version la plus récente de la série 2 a été installée au lieu de la version 4.17.11. Nous trouverons un élément de réponse dans le fichier package.json :

L’exécutable npm respecte la version indiquée dans le fichier package.json si aucune autre n’est précisée dans la commande. Si la dépendance n’est pas listée, alors l’exécutable npm installe la version la plus récente.

L’étiquette latest explicite notre envie d’installer la version la plus récente et sans tenir compte du fichier package.json :

Nous sommes désormais en mesure de choisir entre différentes versions d’un module et de manière plus ou moins fine.

Nous prendrons le temps d’explorer le mécanisme de numérotation des versions dans la section suivante afin de mieux comprendre ce qui est renseigné dans le fichier package.json.

Les numéros de versions ont été utilisés de deux manières dans les sections précédentes : avec l’exécutable npm et en observant la liste de dépendances dans le fichier package.json.

L’exécutable npm découpe un numéro de version en trois parties : majeure, mineure et patch. Pour le numéro de version 1.2.3, 1 indique la version majeure, 2 la version mineure et 3 la version patch.

Si nous devions mettre à jour lodash@2.2.0 :

Une mise à jour majeure demande de lire attentivement la documentation du module pour comprendre le volume de travail à fournir avant de monter en version. La mise à jour mineure peut occasionnellement demander du travail selon l’interprétation des développeurs de modules npm.

Je ne pense pas qu’il soit nécessaire de toujours choisir la dernière version majeure. Les versions patch et mineures sont plus importantes à mes yeux, car elles contiennent des corrections dont bénéficient nos applications.

Nous avons appris à installer des modules npm dans les versions de notre choix et à les réinstaller depuis la liste contenue dans le fichier package.json. Comment savoir s’il faut les mettre à jour ?

L’utilisation combinée des commandes npm outdated et npm update va nous permettre d’y arriver.

Commençons par installer d’anciennes versions des modules lodash et cowsay :

La commande npm outdated affiche les dépendances qui ne sont pas à jour :

Le numéro de version affiché dans la colonne Wanted est celui qui sera atteint avec la commande npm update.

Observons ce qui a changé dans les résultats de la commande npm outdated :

Les modules cowsay et lodash ont été mis à jour au plus sûr et seul le deuxième est désormais listé ; il peut rester en l’état si nous n’avons pas le temps de rendre notre code compatible avec ses changements.

Sinon, une installation manuelle s’impose avec l’étiquette latest :

Un dernier appel à npm outdated nous en donne le cœur net :

Si rien ne s’affiche, c’est que tout est bon : nos modules sont à jour !

Il arrive que l’auteur·e d’un module npm corrige un problème sans publier le correctif sur le registre npm. Il arrive aussi qu’un module soit hébergé de manière publique ou privée sur une plate-forme d’hébergement Git comme GitLab ou GitHub, sans passer par le registre npm.

Le module cowsay est publié sur le registre npm, mais il est aussi hébergé sur GitHub à l’adresse github.com/piuccio/cowsay. Installons-le depuis cette source :

L’exécutable npm vérifie qu’un fichier package.json est situé à la racine du dépôt. Dans ce cas de figure, il utilise le programme Git pour obtenir le code source du module.

Une écriture raccourcie existe pour installer un module depuis un hébergement Git populaire, sans avoir à écrire l’URL en entier :

L’exécutable npm sait aussi installer des modules avec le protocole Secure Shell (SSH) désigné par git+ssh :

Les clients Git et SSH doivent être configurés au niveau du système pour être en mesure de s’authentifier sur l’hôte distant.

C’est une solution intéressante pour automatiser l’installation de modules privés. L’étape suivante serait de déployer un registre npm privé ou de souscrire une option payante sur le registre principal.

Les dépendances de développement sont des modules npm utilisés pour exécuter les tests unitaires ou pour de l’outillage sont aussi des dépendances de développement. Ce sont des modules que nous n’appelons pas directement avec les fonctions require() et import.

Par exemple, le module npm mocha est utilisé pour structurer et exécuter des tests unitaires pour Node et les navigateurs web. Il est donc logique de l’installer comme dépendance de développement. L’option --save-dev signale cette intention à l’exécutable npm :

L’exécutable npm range alors ce module dans une nouvelle section du fichier package.json – la section devDependencies :

Certains modules npm s’installent comme des programmes exécutables. Ils s’appellent ensuite dans un terminal, exactement comme nous le faisions jusqu’à présent avec l’exécutable npm.

C’est le cas du module serve (npmjs.com/serve), par exemple. Il démarre un serveur web en ligne de commande pour tester le rendu de fichiers HTML sans avoir à configurer de logiciels comme Apache ou nginx.

L’installation est rendue globale – à l’échelle du système d’exploitation – avec l’utilisation de l’option --global :

L’exécutable serve est disponible suite à l’installation globale :

Le module npm s’exécute de manière transparente, sans invoquer Node ni l’exécutable npm :

Un module installé de manière globale se désinstalle en passant l’option --global à la commande npm uninstall :

Le chapitre 8 sera l’occasion d’entrer plus en détail dans le développement d’exécutables système écrits en ECMAScript.

Le script npm start concerne les projets dont le script principal tourne en continu – une application web par exemple.

L’exemple suivant démarre un serveur web sans que nous ayons à connaître la commande associée :

Nous sommes libres de renseigner la valeur du champ scripts.start du fichier package.json comme bon nous semble :

Nous avons utilisé le module npm micro (npmjs.com/micro) pour démarrer une application web. Plus exactement, nous avons utilisé l’exécutable fourni par ce module.

Nous verrons dans le chapitre 6 que les plates-formes de service utilisent aussi la valeur du champ scripts.start pour déterminer comment démarrer notre application.

Le script npm test concerne tous les projets pour lesquels nous avons écrit des tests qu’ils soient unitaires ou fonctionnels.

L’intention de la commande lancée par le script npm est de terminer en erreur si un des tests n’aboutit pas au résultat escompté.

L’exemple suivant lance un test unitaire qui s’assure de la cohérence d’un des exemples précédents :

Cette fois-ci, nous avons personnalisé la valeur du champ scripts.test du fichier package.json :

Nous avons eu recours au module npm mocha (npmjs.com/mocha), de même qu’avec le script de démarrage, nous nous sommes basés sur l’exécutable fourni par le module. En revanche, nous l’avons listé dans la section devDependencies car il est relatif à l’outillage du projet.

Les services d’intégration continue lancent le script npm test lorsqu’ils détectent qu’ils ont affaire à un projet Node.

Les scripts npm personnalisés sont utiles lorsque nous souhaitons outiller notre projet sans forcément que ce soit en rapport avec le lancement des tests ou de l’application.

Les scripts personnalisés se démarrent avec npm run :

Nous avons créé ce script en configurant la valeur du champ scripts.print-args du fichier package.json :

Avec le temps, j’ai développé les conventions suivantes :

Un script npm peut faire appel à d’autres :

J’ai plutôt tendance à découper mes scripts de sorte à ce qu’ils fassent tous une chose et une seule. Je peux ainsi les appeler de manière individuelle.

La section suivante va nous aider à orchestrer l’exécution des scripts les uns par rapport aux autres.

L’ordre d’exécution des scripts se contrôle en utilisant les préfixes pre et post. Par exemple, les scripts nommés pretest et posttest seront exécutés respectivement avant et après le script test.

Dans cet exemple de configuration, l’exécution de la commande npm test lancera d’abord le script pretest, puis lint puis enfin test :

Ce mécanisme est utile pour s’intercaler sur des temps particuliers du cycle de vie d’un projet Node. En voici une sélection.

Les scripts npm suffisent à outiller la majorité des projets. Cependant ils deviennent difficiles à lire lorsque les lignes deviennent trop longues.

npm-run-all (npmjs.com/npm-run-all) est un module qui parallélise leur exécution et simplifie l’appel d’un groupe de scripts.

Il est aussi possible de déclencher des actions parallèles après une première action séquentielle.

Ils vous appartient d’orchestrer les scripts en les groupant avec un motif de noms ainsi qu’en combinant les options --parallel (alias -p) et --sequential (alias -s) pour activer ou désactiver le parallélisme d’exécution.

La commande npm view donne une vue synthétique d’un module npm donné. Elle est similaire à celle que nous pourrions trouver sur le registre npm, mais condensée pour l’affichage dans un terminal.

Nous y retrouvons des informations fournies par les personnes en charge du module ainsi que d’autres, fournies par le registre npm.

Nous pouvons aussi zoomer sur une métadonnée. Par exemple, spécifions le champ dependencies pour ne lister que les dépendances directes :

Il est même possible de zoomer sur un niveau plus fin de métadonnée, avec une annotation similaire à celle d’un objet ECMAScript :

L'installation globale est idéale pour disposer d’un module npm sous forme d’exécutable système. On peut cependant vite arriver à en installer beaucoup sans vraiment penser à les enlever quand on n’en a plus besoin.

L’exécutable npx (pour npm executable) s’installe automatiquement avec npm. Il agit comme un raccourci : il va récupérer le module désiré et l’exécute en lui passant les arguments souhaités.

C’est en quelque sorte l’équivalent des trois commandes suivantes :

Vous vous demandez où trouver davantage de documentation à propos d’un module npm ? npm home ouvre un nouvel onglet de navigateur et dirige ce dernier vers sur le site web du module de votre choix.

La commande npm audit part à la recherche de vulnérabilités connues dans l’intégralité des dépendances d’un projet.

npm install effectue un audit de manière implicite afin de s’assurer que notre projet n’est pas compromis à notre insu. Les deux dernières lignes sont issues de la fonctionnalité d’audit de sécurité :

Un affichage plus détaillé est présenté en exécutant npm audit :

Chaque module concerné par une faille connue est listé à l’écran (champ Package). Le champ Path spécifie l’arbre de dépendances qui mène à la vulnérabilité – c’est utile pour identifier quelle dépendance directe actualiser.

La commande npm audit précise la marche à suivre dès qu’elle le peut. Ici, elle indique qu’une mise à jour majeure est nécessaire pour se débarrasser du problème. Cela nécessitera peut-être d’ajuster le code utilisant cette dépendance sous peine de casser notre application.

La commande npm audit fix corrigera toutes les dépendances pour lesquelles il est possible de changer la version de manière automatique et sans risque. Les mises à jour majeures sont toujours manuelles et demandent votre intervention.

La commande npm clean-install (npm ci) est destinée à installer les modules listés dans le fichier package.json. Elle vise à s’exécuter plus rapidement et dans des environnements autres que ceux de développement : en intégration continue, en production, etc.

Cette commande fait une chose de plus que npm install : elle supprime systématiquement le répertoire node_modules pour rendre chaque installation reproductible à l’identique. Elle fait aussi une chose de moins : elle se contente d’installer les modules tels que listés dans le fichier package-lock.json. C’est ce dernier point qui rend cette commande si rapide – moins de vérifications, moins d’allers-retours, moins de complexité.

npm doctor est une commande utilitaire qui vérifie que npm trouve tout ce qu’il lui faut pour bien fonctionner.

L’exécutable npm inspecte le système à la recherche de Git, teste la connectivité vers le registre npm et s’assure qu’il a accès en écriture à des répertoires essentiels à son bon fonctionnement.

La commande npm config affiche et modifie la configuration de l’exécutable npm. Elle se découpe en plusieurs sous-commandes comme en atteste cette tentative d’utilisation :

La sous-commande get affiche la valeur par défaut d’une clé de configuration :

Cette configuration reflète le degré d’affichage de l’exécutable. Elle agit comme un curseur pour choisir une vue plus ou moins détaillée de ce qui se trame sous le capot.

Augmentons le taux d’affichage avec la sous-commande set :

Nous voyons désormais les requêtes HTTP lancées (ici, en rejouant l’exemple d'installation globale du module serve) :

La sous-commande ls récapitule tous nos changements de configuration. Elle affiche tous les réglages par défaut en la suffixant de l’option --long :

Pour y voir plus clair, voici une petite sélection des éléments de configuration que vous pourriez être amené·e à modifier sur votre machine de développement ou sur votre configuration de production :

Nous savons comment installer des modules depuis le registre, mais nous n’avons pas encore vu comment contribuer nous-même à cet écosystème.

L’option --dry-run est peut-être la première à utiliser avec cette commande, puisqu’elle fait comme si nous voulions publier le module, mais sans aller jusqu’à téléverser le code sur le registre npm. Je la recommande pour voir de nos propres yeux ce qui serait transmis et rectifier un problème avant qu’il ne se produise – vous n’avez pas envie de mettre en ligne un fichier qui contient un mot de passe n’est-ce pas ?

La publication d’un module implique que vous ayez configuré les sections main ou bin du fichier package.json pour respectivement indiquer quel fichier charger avec require('<module>') ou exécuter avec npx <module>.

La publication d’un module nécessite de se créer un compte sur le registre npmjs.com. Si c’est la première fois, l’exécutable npm vous demandera alors de vous identifier – le module sera ensuite publié en votre nom.

Idéalement, je recommande de ne pas publier de module à la main mais de préférer l’utilisation d’un service d’intégration continue comme Travis CI (travis-ci.com). La configuration d’un tel service permet de publier une nouvelle version seulement si les tests passent au vert.

Nous ne pouvons pas publier deux fois une même version d’un module npm. Nous devons donc a minima modifier la valeur de la section version dans le fichier package.json.

La commande npm version automatise le calcul du prochain numéro de version, reflète ce dernier dans le champ version du fichier package.json et procède à un commit Git, étiqueté avec cette nouvelle version. Je trouve cette manière élégante, notamment en complément de la publication automatique par le biais d’un service d’intégration continue.

La commande npm version se complète forcément d’un argument pour indiquer la granularité de version sémantique concernée. Ainsi, si nous voulons mettre à jour un module actuellement en version 1.0.0 :

Cette montée en version se complète optionnellement de scripts npm pour automatiser d’autres actions lors d’une montée en version :

De nouvelles versions de l’exécutable npm sont régulièrement publiées. Un message s’affiche dans notre terminal lorsque nous l’utilisons et qu’il détecte qu’une version plus récente est disponible.

Le module qui contient l’exécutable npm suit le principe des versions sémantiques. Ainsi, la mise à jour sera sans effort si le numéro majeur reste le même.

J’ai tendance à regarder du côté de github.com/npm/npm/releases pour lire tous les Breaking Changes et comprendre en quoi la mise à jour majeure m’affecte.

Le fichier package-lock.json est créé automatiquement par l’exécutable npm dès que vous ajoutez votre première dépendance à un projet.

Jetons un œil à son contenu pour tenter d’en cerner les contours :

Il ressemble beaucoup au fichier package.json. On notera qu’il contient exclusivement des données liées aux dépendances, ainsi qu’à toutes les dépendances des dépendances.

Si le fichier package.json contient une version sémantique, package-lock.json contient la version exacte de chaque dépendance ainsi que deux autres types d’informations : l’URL de téléchargement et une signature qui sert à vérifier si le fichier téléchargé est le bon (intégrité).

La représentation complète de l’arbre de dépendances dans le fichier package-lock.json traduit deux intentions : rendre l’installation des dépendances possibles en se basant uniquement sur ce fichier et accélérer le processus d’installation.

bower (bower.io) est un gestionnaire de modules spécialisé dans le développement front-end.

Je pense qu’il était utile à une époque où l’outillage front-end disponible dans Node était encore confidentiel. Je pense aussi que cette époque est révolue, au sens où l’outillage dédié à Node et aux navigateurs web tend à se confondre.

En apprenant ECMAScript, Node et npm, nous gagnons non seulement un outillage disponible immédiatement, mais aussi la capacité à créer le nôtre. Pour en savoir plus sur comment développer pour le front-end comme on développe pour Node, je vous invite à lire le chapitre 9.

Le contenu du répertoire node_modules se recrée automatiquement en utilisant l’exécutable npm, que ce soit avec npm install ou npm update. Mieux vaut versionner les fichiers package.json et package-lock.json pour être certain·e de les recréer comme il faut.

Le répertoire node_modules n’a donc pas besoin d’être versionné. Je vous encourage à ajouter node_modules dans le fichier .gitignore. Ce fichier texte se situe en général à la racine de votre projet.

L’application Yarn (yarnpkg.com) veut être une alternative à l’exécutable npm. Le programme vise une installation rapide, hors-ligne et sécurisée.

npm rattrape régulièrement les fonctionnalités qui “donnent de l’avance” à Yarn. Le choix tient donc plutôt du goût ou de l’idéologie. Essayez donc Yarn et gardez-le pour les bonnes raisons – les vôtres.

L’exécutable npm passe le plus clair de son temps à faire des allers-retours vers le registre npm en utilisant votre connexion Internet. Il téléchargera un module seulement s’il ne l’a pas déjà téléchargé sur un autre projet.

L’équipe de développement de l’exécutable npm travaille à améliorer ses performances et sa qualité d’utilisation. Cette équipe n’a pas d’influence sur les choix faits par les personnes en charge des modules.

Le temps de téléchargement d’un module npm dépend de deux choses : du nombre de dépendances à installer et de leur poids, lequel correspond à la somme des poids des scripts et des ressources additionnelles (images, documentation). Dans les deux cas, plus il y en a, plus l’installation prendra du temps.

Par exemple, le seul ajout de webpack 4 (npmjs.com/webpack) augmente le coût de téléchargement de 14 Mo lors de npm install. Ce n’est pas rien et ce n’est certainement pas la faute de l’exécutable npm.

Le service en ligne Package Phobia (packagephobia.now.sh) garde un historique du poids des modules npm. Celui de webpack se trouve sur packagephobia.now.sh/result?p=webpack.

L’exécutable npm est généreux en messages pendant l’installation de modules. C’est parfois difficile à lire, notamment pour comprendre la raison du message et la solution à apporter.

Si npm WARN s’affiche, ce n’est pas une erreur mais un message à caractère informatif.
Si npm ERR débute la ligne, il y a un problème sur lequel nous avons une action immédiate à mener.