Un guide sur npm : le gestionnaire de packages Node.js

JavaScript est de loin le langage le plus utilisé pour le développement de sites Web et d'applications Web. La multitude de ressources est stupéfiante, et plus encore, le nombre de bibliothèques disponibles.

Au début, ces bibliothèques sont peu nombreuses et faciles à entretenir ; cependant, assez tôt, l'enfer de la dépendance s'installe et une solution plus mature est nécessaire.

Entrez le Node Package Manager (npm) - un gestionnaire de packages JavaScript notamment utilisé conjointement avec Node.js, bien qu'il puisse également être utilisé indépendamment. Il vous donne un contrôle exceptionnel sur les dépendances de votre projet et constitue un excellent moyen de contribuer au monde open source.

Vous pouvez commencer en exécutant simplement npm install <package name> et en l'injectant dans votre fichier JavaScript.

Vous souhaitez installer une version spécifique ? Aucun problème. Exécutez npm install <package name>@1.2.3 .

Vous souhaitez installer un package globalement (comme Mocha ou Angular-CLI) ? Ajoutez simplement un -g comme ceci : npm install -g angular-cli mocha .

Certes, la plupart des cas d'utilisation s'arrêtent à une installation npm, et rien d'autre n'est nécessaire. Cependant, npm a de nombreuses fonctionnalités supplémentaires, que je vais vous expliquer, en soulignant celles que je considère comme essentielles, vraiment utiles ou tout simplement géniales.

Commandes CLI

La CLI est l'endroit où les utilisateurs passent le plus clair de leur temps à interagir avec npm, et son interface d'aide est réellement utile.

L'interrogation de l'aide ( npm help ) génère un éventail complet d'options, et l'exécution de npm help-search <searchText> vous donne une liste des résultats de recherche directement à partir du npm markdown.

Voici les commandes de base qui se démarquent.

• install : Il est mentionné ici en raison de sa nécessité absolue lorsque vous travaillez avec npm. Utilisé pour installer un nouveau package localement ou globalement (lors de l'ajout de -g ) ou pour installer les dépendances répertoriées dans le fichier package.json (plus à ce sujet plus tard).

• uninstall : C'est aussi un élément essentiel. Il est utilisé pour purger un package spécifique du répertoire node_modules localement ou globalement (lors de l'ajout de -g ).

• access : Il s'agit du terrain de jeu des administrateurs d'autorisations d'utilisateurs npm dans le contexte npm-organizations et des packages étendus (privés). Des trucs vraiment puissants. Utilisé en conjonction avec adduser , owner , team , etc., il donne un contrôle précis sur qui a accès à quoi.

• bin : Où diable sont installés les packages ? Exécutez cette commande pour voir le chemin d'accès absolu au fichier.

• cache : Si vous commencez à installer des packages à partir de npm left, right et center, cette commande est très utile. Appelez-le avec la sous-commande ls pour voir une liste des packages mis en cache localement ou avec la sous-commande clean pour effacer tous les packages qui se trouvent dans le cache. À l'époque où le registre npm était encore un peu instable, c'était essentiel pour revenir à un environnement stable ou pour réinitialiser les choses lorsque vous n'aviez pas correctement configuré les autorisations npm.

• config : nous aborderons les différentes options de configuration plus tard, mais cette commande traite principalement de la persistance des propriétés de configuration dans le fichier de configuration local ou global en utilisant les sous-commandes set , get ou delete .

• dedupe ou ddp : lorsque vous travaillez sur un projet sur une longue période et que vous installez des packages directement à partir de npm, cette commande parcourra l'arborescence locale des packages et tentera de simplifier les dépendances.

• link : Lorsque vous développez votre propre package npm, cela vous permet de créer un lien symbolique vers le contexte global afin qu'il puisse être testé comme s'il était installé globalement à partir du registre npm. Par exemple, si vous écrivez un outil d'assemblage dans un nœud sur lequel une CLI est installée globalement, vous pouvez exécuter cette commande et tester le comportement de votre CLI sans avoir à la déployer au préalable.

• ls : Il est utilisé pour visualiser les dépendances des packages et leurs dépendances, dans une structure arborescente. C'est cool à voir et c'est aussi utile pour des comparaisons avec d'autres projets.

• outdated : Ceci est utilisé pour évaluer l'état actuel des dépendances installées et si elles sont obsolètes ou non. Dans les projets où la liste des dépendances racine compte des centaines de lignes, une vérification manuelle des packages est presque impossible. L'ajout -g --depth=0 à cette commande vous permet également de vérifier vos packages installés globalement.

• publish : Cette commande est essentielle lors du développement de votre propre package pour npm. Il fait exactement comme son nom l'indique; il publie votre package dans le registre npm.

• search : utilisez ceci pour rechercher dans le registre tous les packages contenant le texte fourni dans le troisième argument.

• shrinkwrap : En bref, cette commande vous permet de verrouiller des versions de dépendance spécifiques dans un package dans l'ordre, de sorte qu'un numéro de semver (version sémantique) détendu ne casse pas le code de production.

• star : Aimez-vous vraiment un package que vous utilisez ? Utilisez cette commande pour montrer votre appréciation directement depuis le terminal, qui se reflète ensuite sur la page du package dans le registre npm.

• update : Cela suit généralement la commande outdated pour mettre à jour tous les packages obsolètes.

• version : cela vous donne un raccourci pour remplacer la propriété de version package.json et créer une balise git tout en un.

Notez que la plupart de ces commandes peuvent prendre des sous-commandes et/ou des configurations, et cette liste n'est en aucun cas une discussion exhaustive sur la CLI.

npm-config

La configuration est une partie importante de npm, et il existe plusieurs façons de définir les variables de configuration.

Configuration via CLI et variables d'environnement

Tout d'abord, la configuration peut être définie via la CLI depuis le terminal.

En règle générale, cela ressemblerait à ceci : npm <command> --<configuration option> [<optional value>] .

Si la valeur n'est pas spécifiée, l'option sera définie sur true par défaut.

Par exemple, supposons que vous travaillez sur un package npm étendu (privé) et que vous décidez de le publier en tant que package public.

Cela se fait facilement en ajoutant --access=public à votre commande de publish . Si nous ne spécifions pas que la propriété soit publique, la valeur par défaut serait restreinte (privée).

La configuration ajoutée à d'autres commandes comme celle-ci ne persiste pas partout, il peut donc devenir fastidieux de définir un tableau de configurations via la CLI.

Dans ces cas, il peut être préférable de définir la configuration à l'aide de variables d'environnement.

Toute variable d'environnement définie avec le préfixe npm_config_ sera utilisée pour configurer npm.

Par exemple : export npm_config_registry=localhost:4321 définirait l'option de configuration du registre globalement, et lorsque npm est exécuté, il utilisera le registre npm situé sur localhost sur le port 4321.

Configuration via le fichier npmrc

Vous pouvez également définir des options de configuration à l'aide du fichier spécial .npmrc , qui peut être défini à différents niveaux en fonction de vos besoins :

• Niveau projet : à la racine du code d'un projet avec son fichier package.json , généralement path/to/project/.npmrc
• Niveau utilisateur : le répertoire qui configure le compte d'un utilisateur spécifique, généralement ~/.npmrc
• Niveau global : le répertoire dans lequel npm recherche les configurations globales, généralement $PREFIX/etc/npmrc
• Niveau intégré : Soyez prudent. Cette configuration n'est pas seulement globale, mais elle fait également partie du code source npm, et les meilleures pratiques recommandent (en fait exigent) que nous ne modifiions pas le code dont nous ne sommes pas responsables. Il se trouve généralement dans /path/to/npm/npmrc .

Les paramètres de configuration du fichier .npmrc peuvent être modifiés et conservés à l'aide de l'interface de ligne de commande en exécutant une commande au format suivant : npm config set <key> <value> .

Par exemple, vous pouvez exécuter npm config set access public pour rendre publique de façon persistante la configuration de publication d'un package délimité (privé).

Par défaut, cette commande conserverait la configuration localement (la configuration au niveau de l'utilisateur comme décrit ci-dessus), mais vous pouvez ajouter -g pour la conserver globalement.

Lorsque la configuration persistante doit se produire au niveau du projet ou au niveau intégré, le fichier .npmrc doit être modifié à l'aide d'un éditeur de texte.

Configuration via package.json

Enfin, la configuration peut être définie à partir du fichier package.json . Cependant, cela est rarement utilisé (et ne doit être utilisé que si cela est explicitement requis), car un fichier .npmrc au niveau du projet est l'endroit préféré par convention pour définir la configuration du package.

Paramètres de configuration notables

• access : Comme indiqué ci-dessus, il est utilisé pour définir les autorisations.

• always-auth : Il est important de noter que ce paramètre par défaut est false. Lorsqu'il est défini sur true, npm exigera toujours une authentification lors de la prise de contact avec le registre.

• ca : par défaut, l'autorité de certification (CA) npm. Il peut être modifié en null pour autoriser l'accès uniquement aux bureaux d'enregistrement connus, ou à un certificat CA spécifique pour n'accorder l'accès qu'à celui-ci. Ce paramètre, ainsi que cafile , cert et strict-ssl , sont rarement utilisés, mais parlent de l'aspect sécurité et fiabilité de npm, permettant la tranquillité d'esprit en sachant que le paquet que vous installez provient de la source que vous attendez.

• color : La valeur par défaut est true, ce qui vous permet de rompre avec la morosité standard du terminal en colorant la stdout autorisée par les descripteurs de fichiers tty. S'il est défini sur false, le terminal reste terne. Lorsqu'il est défini sur always , il sort toujours en couleur.

• depth : ce paramètre permet un contrôle granulaire de ce que vous voyez avec des commandes récursives, telles que ls et outdated , en attribuant la profondeur à laquelle elles sont exécutées. Une valeur de 0 n'évaluera que le premier niveau de dépendances tandis que l'infini (valeur par défaut) entraînera l'évaluation de tous les niveaux de dépendances. L'exception à cette règle est lorsque vous l'utilisez avec outdated ; dans ce cas, l'infini est interprété comme 0 pour assurer une sortie plus pertinente.

• dev : Ceci est défini sur false par défaut, mais lorsqu'il est défini sur true (lors d'une npm install ), toutes les dépendances de développement dans le fichier package.json seront installées avec les dépendances normales.

• dry-run : lorsque ce paramètre est défini sur true, npm n'apportera aucune modification à votre package mais vous indiquera à la place ce qu'il aurait fait. Cela peut être très utile lors de l'exécution de certaines commandes, telles que dedupe ou update .

  

• git-tag-version : Il est défini sur true par défaut. Ce paramètre marque une version dans git lors de l'exécution de la commande npm version . Si vous utilisez npm comme gestionnaire de packages pour un grand projet qui a des versions balisées dans git, cela peut vous faire gagner du temps et n'oubliez pas de mettre à jour le fichier package.json pour vous.

• loglevel : Par défaut, ceci est défini sur warn , ce qui donne une sortie d'erreur et d'avertissement lors de l'exécution des commandes npm. Les autres paramètres incluent silent , qui ne fournit aucune sortie ; error , qui enregistre uniquement les erreurs dans la sortie ; http , qui n'annonce que les erreurs de requête http ; info , pour vouloir une sortie informative); verbose , qui enregistre presque tout ; et silly , qui, comme son nom l'indique, donne une quantité stupide de sortie et plus encore.

• production : Lorsque ceci est défini sur true, npm agit en conséquence et exécute toutes les commandes en mode production. Cela signifie que le développement ou les dépendances facultatives ne seront pas installées, et aucune tâche liée au développement ne sera exécutée.

• rollback : lorsqu'il est défini sur true, toutes les installations ayant échoué sont supprimées. Cela s'avère pratique lorsqu'une installation de dépendances échoue. En fonction de votre niveau de journalisation, vous devriez pouvoir voir quelles installations ont échoué, en prendre note et exécuter la commande npm install avec l'option rollback définie sur true. Ensuite, avec vos notes et une installation à sec (comme décrit ci-dessus), vous pouvez ensuite déboguer le problème.

• save : When installing a package directly from the registry, you can append –save to the command which will add the installed package to the dependencies option in the file. For example, file. For example, npm install lodash` ajoutera lodash à vos dépendances.

• save-dev : Semblable à l'option save configuration, ajoutez --save-dev lors de l'installation d'un package, et il sera ensuite ajouté à l'option devDependencies dans le fichier package.json .

• save-optional : Semblable à l'option save configuration, ajoutez --save-optional lors de l'installation d'un package, et il sera ensuite ajouté à l'option optionalDependencies dans le fichier package.json .

• save-exact : lors de l'installation de packages, les options save , save-dev et save-optional modifient le fichier package.json en insérant le package installé dans sa propriété respective avec un opérateur de plage semver. Lors de l'appel du paramètre de configuration 'save-exact' avec une valeur true, en conjonction avec l'un des paramètres mentionnés ci-dessus, un numéro de version spécifique est utilisé, ignorant la plage semver.

• save-prefix : Cela définit l'opérateur de plage semver lors de l'utilisation de save , save-dev ou save-optional . La valeur par défaut est ^ , permettant aux mises à niveau mineures des packages de se produire lors de l'installation. Cela peut être défini sur n'importe quel opérateur de plage semver préfixé valide.

• tag-version-prefix : la valeur par défaut conventionnelle est v , spécifiant ce qui est ajouté à la version de la balise git lors de l'exécution de npm version .

Mise à jour de npm Utilisation de npm

Vous pouvez également utiliser npm pour se mettre à jour.

Exécutez simplement npm install -g npm@latest et npm sera mis à jour vers la dernière version stable. Il est important de noter que chaque version de Node.js est livrée avec une version spécifique de npm, et d'après mon expérience, vous ne devriez pas trop jouer avec cet appariement.

En fin de compte, ma recommandation est de s'en tenir à l'appariement tel qu'il est prévu.

Lorsque vous utilisez npm en tant qu'outil autonome, assurez-vous de comprendre les implications de l'utilisation de la version que vous choisissez. Il existe un excellent outil pour gérer différentes versions de Node.js (et à leur tour les versions npm) sur le même système appelé nvm.

Le fichier package.json

Le fichier package.json est l'élément crucial qui relie tout ensemble.

C'est une exigence pour publier un paquet dans le registre npm, et c'est là que la partie gestion des dépendances prend vie.

Il a deux champs obligatoires, à savoir "nom" et "version", et ensemble ces propriétés doivent être un identifiant unique.

Le champ de nom doit respecter certaines règles, telles que définies par la documentation npm sur la dénomination, et le champ de version est soumis aux spécifications de semver.

En plus de cela, vous pouvez avoir une liste de dépendances longue d'un kilomètre et définir une version spécifique à utiliser pour chacune d'elles, en utilisant les versions semver et les opérateurs de plage. Voici une liste d'autres propriétés notables.

"principale"

"main" définit le point d'entrée de votre application, qui est par défaut index.js . Selon la convention ou votre framework, il peut s'agir app.js ou main.js . Vous pouvez, bien sûr, en faire tout ce que vous voulez.

"scénarios"

C'est une propriété sous-estimée.

Tout d'abord, il peut être utilisé pour faire des choses sur la prépublication.

Deuxièmement, il fournit un endroit où vous pouvez aliaser un tableau de commandes fréquemment utilisées, allant des tâches de construction (définies dans gulp ou grunt), déclenchant l'installation d'autres dépendances (avec quelque chose comme bower), démarrage d'un serveur de développement avec webpack, ou exécutant un ensemble de commandes bash.

"dépendances"

Cette propriété est une liste de packages nécessaires à votre application, ainsi que le numéro de semver compatible. C'est une propriété notable car elle peut être modifiée depuis le terminal lorsque vous installez des packages locaux.

Cela se fait en ajoutant --save (ou le raccourci -S ) à la fin de la commande npm install .

Lorsque vous faites cela, le ou les packages nouvellement installés sont ajoutés à la liste des dépendances dans votre fichier package.json .

De même, une dépendance peut également être supprimée en ajoutant --save lors de l'exécution de la commande npm uninstall .

Il est important d'être conscient des modèles de version de Semver de chacune des dépendances et de ce qu'ils signifient.

Si la règle semver est trop stricte, vous perdez de nouvelles fonctionnalités et améliorations, alors que si la règle semver est trop détendue, une version de rupture d'un paquet peut être installée le long de la ligne.

Une installation de package cassée peut s'avérer assez difficile à résoudre, en particulier lorsque la version réduite du package est utilisée.

"devDépendances"

Séparée de la propriété dependencies, la propriété "devDependencies" vous permet de définir des dépendances qui ne sont utilisées que pendant la phase de développement et ne sont pas nécessaires pour la construction de production (comme ESLint, les packages grunt-contrib et Protractor). Tout comme pour les dépendances, cette propriété peut être modifiée depuis le terminal en ajoutant --save-dev (ou le raccourci -D ) à la fin de la commande npm install ou de la commande npm uninstall . La même prudence s'applique à la gestion des versions comme mentionné dans les dépendances.

"poubelle"

C'est ici que vous pouvez spécifier le ou les fichiers exécutables de votre package, comme le chemin d'accès à un utilitaire CLI. Cette propriété indique à npm de créer des liens symboliques locaux ou globaux vers vos exécutables lorsque votre package est installé.

« config »

Comme indiqué précédemment, c'est ici que vous définissez les paramètres de configuration via votre fichier package.json .

"privé"

Lorsqu'il est défini sur true, npm refusera de publier le package.

Cela ne doit pas être confondu avec le paramètre de configuration d'accès.

Il s'agit d'un paramètre pratique lorsque vous avez un projet qui utilise npm avec son package.json mais qu'il n'est pas destiné à être publié dans le registre npm, qu'il soit étendu ou public.

Si votre intention change, modifiez simplement le paramètre sur false et vous pourrez publier votre package.

Propriétés personnalisées

Le fichier package.json accepte également les propriétés personnalisées, tant que le nom n'est pas déjà défini ou réservé.

Développer votre propre package npm

L'écosystème npm est rempli de packages, écrits par des milliers de développeurs différents à travers le monde. Chacun résout une sorte de problème, fournissant une abstraction ou présentant une implémentation de quelque chose.

Il y a de fortes chances qu'à un moment donné, vous souhaitiez également développer votre propre package à partager.

Tout d'abord, vous devez créer un fichier package.json avec les propriétés minimales requises de "name" et "version", puis la propriété "main" pour spécifier le point d'entrée, par exemple index.js.

Écrivez votre code dans ce fichier index.js, connectez-vous avec votre compte d'utilisateur npm ou créez un nouvel utilisateur à partir du terminal, et vous êtes prêt à le publier dans le registre npm.

Les forfaits peuvent être publics ou privés.

Les packages publics sont gratuits à publier et sont disponibles pour tout le monde.

Les packages privés, appelés packages étendus, ne peuvent être publiés que si vous avez payé l'utilisateur de modules privés, et ils peuvent être identifiés par le @username/ distinct qui est ajouté au nom du package.

Les packages délimités peuvent également être publiés publiquement en appelant la commande de publish avec --access=public .

De plus, si vous passez plus de temps à développer et à améliorer la base de code de votre package, et qu'il est temps de publier une nouvelle version, vous modifiez simplement la version (conformément aux règles et conventions semver) du package dans le package.json fichier et tapez npm publish .

Vous pouvez également utiliser l'interface de ligne de commande et appeler npm version <update_type> , où update_type est soit patch , minor , soit major , comme décrit par semver, et cela incrémente ensuite automatiquement le numéro de version dans le fichier package.json .

Organisations npm

Encore une fois, la documentation npm pour cela est excellente, et il serait vain de simplement répéter leurs mots.

Ce que l'on peut dire des organisations dans le contexte du npm, c'est qu'elles sont extrêmement fines et, lorsqu'elles sont gérées correctement, de grandes équipes et des individus, travaillant sur des packages étendus ou publics sous un même nom, peuvent être très bien gérés et restreints.

Bien qu'il soit complexe à maîtriser, il est très enrichissant.

Le pouvoir du npm

En fin de compte, la documentation fournie par npm est vaste et doit être consultée pour plus de détails, mais cet article fournit un aperçu utile des fonctionnalités de base et plus avancées, illustrant la génialité de npm.

Comme pour toutes choses, des opinions fortes existent et de nombreux défauts peuvent être trouvés. Mais si vous n'avez jamais essayé npm (ou node, d'ailleurs), plongez-y et explorez-le par vous-même. Il y a de fortes chances que vous l'apprécierez plus que vous ne le pensez.

Pour des articles plus intéressants sur npm, pensez à lire Utilisation de Scala.js avec npm et Browserify.