Dans l’écosystème Typescript et plus généralement Javascript, il existe une multitude d’outils et de bibliothèques. Ces outils et ces bibliothèques peuvent être utilisés pendant l’exécution de l’application, pour aider aux développements, pour exécuter des tests ou pour aider au déploiement. La multitude des fonctionnalités de ces outils implique des méthodes d’installation spécifiques, des configurations particulières et surtout des cas d’utilisation souvent très différents.

Le plus souvent une application générée à partir de code Typescript est exécutée sur un serveur Node.js et dans cet environnement, un outil est incontournable pour aider à utiliser des bibliothèques tierces. Cet outil est npm (pour Node Package Manager), il sert à gérer les dépendances d’une application Typescript en les organisant sous forme de packages. D’autres gestionnaires existent comme Bower ou yarn.

Le but de cet article est d’expliquer le fonctionnement de npm et d’en expliciter les commandes principales.

npm est installé en même temps que Node.js (pour davantage de détails, voir Installation de Node.js).

Répertoires de npm

Installation par défaut

Après installation, npm est utilisable sous forme d’une commande disponible avec un terminal. Dans le cadre de l’installation qu’on avait effectuée dans l’article Installation de Typescript sur Debian/Ubuntu, Node.js et npm avaient été installés dans le répertoire /usr/node.js, ainsi si on écrit la commande suivante, on doit obtenir le répertoire d’installation de npm:

user@debian:~% whereis npm  
npm: /usr/node.js/node-v8.10.0-linux-x64/bin/npm 

Répertoires contenant les packages

Les packages gérés par npm peuvent être installés suivant 2 modes: local ou global:

• Local: le package installé localement est installé dans un répertoire qui se trouve dans le répertoire de l’application. Ce répertoire est nommé node_modules. Le package est accessible seulement dans le répertoire de l’application. Dans ce mode, chaque application peut utiliser une version spécifique d’un même package.
• Global: le package est installé de façon globale dans un répertoire accessible dans le répertoire d’installation de Node.js. Dans notre cas, ce répertoire est: /usr/node.js/node-v8.10.0-linux-x64/. Si un package est installé dans ce répertoire, il est partagé par toutes les applications.
  Il est possible de modifier le chemin de ce répertoire, ce qu’on fera dans le paragraphe suivant.

Modifier le répertoire global des packages (facultatif)

Le répertoire global par défaut est dans le répertoire d’installation de Node.js. Pour savoir comment est préfixé le répertoire global, il faut afficher le paramètre config de npm en écrivant:

user@debian:~% npm config get prefix 
/usr/node.js/node-v8.10.0-linux-x64 

Ainsi, le répertoire global est <prefix>/lib/node_modules. Dans notre cas, le chemin précis du répertoire global est:

/usr/node.js/node-v8.10.0-linux-x64/lib/node_modules 

Le gros inconvénient d’utiliser ce répertoire est qu’il est nécessaire d’être l’utilisateur root pour gérer les packages qui s’y trouvent. Une possibilité est de modifier le préfixe pour que le répertoire global se trouve dans le répertoire de l’utilisateur. Les droits administrateurs ne sont donc plus nécessaires et l’utilisateur peut mettre à jour plus facilement les packages installés de façon globale. Les packages ne sont plus installés à l’échelle de la machine mais à celle de l’utilisateur.

Pour afficher les éléments de configuration de l’utilisateur courant, il suffit de taper:

user@debian:~% npm config list 
; cli configs 
metrics-registry = "https://registry.npmjs.org/" 
scope = "" 
user-agent = "npm/5.6.0 node/v8.10.0 linux x64" 
  
; node bin location = /usr/node.js/node-v8.10.0-linux-x64/bin/node 
; cwd = /home/user 
; HOME = /home/user 
; "npm config ls -l" to show all defaults. 

Pour modifier la valeur du préfixe:

1. Il faut taper:

   user@debian:~% mkdir .node_modules 
   user@debian:~% npm config set prefix=$HOME/.node_modules 
   

   Si on affiche de nouveau le préfixe après la modification:

   user@debian:~% npm config get prefix 
   /home/user/.node_modules 
   

   Cette opération a créé un fichier de configuration nommé .npmrc dans le répertoire de l’utilisateur. Ce fichier contient désormais la valeur du préfixe:

   user@debian:~% cat .npmrc 
   prefix=/home/user/.node_modules 
   

2. Maintenant si on réinstalle le package npm au niveau global, il sera installé dans le répertoire /home/user/.node_module. Pour installer le package npm au niveau global, on exécute la commande suivante (cette étape se fait sans être l’utilisateur root):

   user@debian:~% npm install npm --global 
   

   En vérifiant, on voit bien que le répertoire global contient des éléments fraîchement installés et il contient aussi les modules installés de façon globale:

   user@debian:~% ls .node_modules 
   bin   etc   lib   share 
   user@debian:~% ls .node_modules/lib/node_modules 
   npm 
   

3. On peut ensuite, modifier le chemin de Node.js dans la variable d’environnement PATH en éditant le fichier .bashrc avec un éditeur de texte. Par exemple, avec vi, on peut exécuter la commande suivante:

   user@debian:~% vi .bashrc 
   

   A la fin du fichier, on peut remplacer les lignes:

   export NODEJS_HOME=/usr/node.js/node-v8.10.0-linux-x64  
   export PATH=$PATH:NODEJS_HOME/bin  
   

   Avec les lignes suivantes, contenant les nouveaux chemins:

   export NODEJS_HOME=$HOME/.node_modules  
   export PATH=$PATH:NODEJS_HOME/bin  
   

   On enregistre en tapant sur la touche [Echap] puis :wq et la touche [Entrée] pour valider.

4. Si on ouvre un nouveau terminal, on devrait avoir un nouveau chemin pour npm:

   user@debian:~% whereis npm  
   npm: /home/user/.node_modules/bin 
   

5. A partir de cette étape, en exécutant npm on peut avoir une erreur du type:

   /usr/bin/env:  'node': No such file or directory 
   

   Cette erreur se produit parce que node n’est plus présent dans le répertoire .node_modules/bin. Il faut donc rajouter un lien symbolique vers l’ancien répertoire en exécutant:

   user@debian:~% cd .node_modules/bin 
   user@debian:~/.node_modules/bin% ln -s  /usr/node.js/node-v8.10.0-linux-x64/bin/node 
   

   On réinstalle ensuite node dans le répertoire global en exécutant:

   user@debian:~/.node_modules/bin% npm install --global node 
   

6. On peut en profiter pour réinstaller Typescript

   user@debian:~% npm install --global typescript  
   

7. On peut vérifier l’installation en exécutant:

   user@debian:~% npm version 
   user@debian:~% node –version 
   

Fichier package.json

Dans le cadre d’un projet, npm utilise un fichier au format JSON nommé package.json qui se trouve à la racine du répertoire du projet. Ce fichier contient des informations comme:

• La description du projet: ce sont des méta-datas comme le nom, la version, la description, la licence et des mots clés associés au projet. Ces informations peuvent être éditées au besoin.
• Les packages nécessaires: il est possible d’installer des packages et d’indiquer la dépendance du projet vers ce package en le rajoutant dans le package.json. Ainsi le fichier package.json peut contenir toutes les dépendances du projet vers des packages gérés par npm. On distingue 2 types de dépendances:
  • Les dépendances de développement: ces packages ne sont utilisés que pour le développement et ne le sont pas en production. Par exemple, il peut s’agir de packages pour compiler le code Typescript, pour exécuter des tests ou des utilitaires pour aider au développement. Ces packages ne doivent pas être déployés en production.

    Ces dépendances sont indiquées dans le fichier package.json dans l’élément devDependencies.

  • Les dépendances utilisées au runtime: ces packages sont utilisés à l’exécution de l’application. Ils doivent donc être déployés en même temps que l’application.
    Ces dépendances sont indiquées dans le fichier package.json dans l’élément dependencies.
• Les applications ou scripts à exécuter: suivant certaines opérations exécutées par npm, il faut exécuter des scripts ou des applications. Ces scripts et ces applications peuvent être indiquées dans le fichier package.json.

Générer un fichier package.json

Il est possible de générer un fichier package.json en exécutant:

user@debian:~/Documents/test_package% npm init 

Un certain nombre de questions sont posées pour remplir les méta-datas associées au projet. Un exemple du fichier généré est:

{ 
  "name": "test_package", 
  "version": "1.0.0", 
  "description": "Description du package test_package", 
  "main": "index.js", 
  "scripts": { 
    "test": "echo \"Error: no test specified\" && exit 1" 
  }, 
  "author": "", 
  "license": "ISC" 
} 

Pour ne pas répondre aux différentes questions et générer le fichier directement, on peut écrire:

user@debian:~/Documents/test_package% npm init --yes 

ou

user@debian:~/Documents/test_package% npm init -y 

Paramétrer des “méta-datas” par défaut

Il est possible de paramétrer les méta-datas appliqués au fichier package.json. Pour paramétrer ces méta-datas, il faut exécuter une commande du type:

user@debian:~% npm config set init.author.name <Nom de l'auteur> 
user@debian:~% npm config set init.author.email <Email de l'auteur> 
user@debian:~% npm config set init.author.url <Url du projet> 
user@debian:~% npm config set init.license <Type de license> 

Il est possible de configurer d’autres éléments, on peut avoir une liste plus exhaustive en exécutant:

npm help 7 config 

Les commandes usuelles de npm

On va lister dans cette partie les commandes les plus courantes.

Afficher de l’aide

On peut afficher un message d’aide en exécutant:

user@debian:~% npm help 

ou

user@debian:~% npm -h 

Pour afficher de l’aide concernant une commande précise:

user@debian:~% npm help <nom de la commande> 

ou

user@debian:~% npm <nom de la commande> -h 

Installation d’un package

Ces commandes permettent d’installer un package. On peut avoir des détails sur les packages en allant sur le site npmjs.com/.

Si on installe un package localement, il sera placé dans un répertoire appelé node_modules dans le répertoire courant. L’installation d’un package localement se fait en exécutant:

user@debian:~% npm install <nom du package> 

ou

user@debian:~% npm i <nom du package> 

Cette commande installera le package et, le cas échéant, toutes ces dépendances.

Après installation, la dépendance sera ajoutée au fichier package.json dans l’élément de configuration dependencies (correspondant aux packages nécessaires à l’exécution).

Ainsi si on exécute la commande suivante:

user@debian:~% npm install protractor 

Le fichier package.json contiendra:

{ 
  "name": "test_package", 
  ..., 
  "dependencies": { 
    "protractor": "^5.3.2" 
  }
} 

Il est possible d’installer plusieurs packages en une seule fois en les listant à la suite:

user@debian:~% npm install <nom package 1> <nom package 2> <nom package 3> <etc...> 

Installer les dépendances indiquées dans package.json

Il suffit d’exécuter cette commande (on ne précise pas d’arguments) dans le répertoire du projet:

user@debian:~% npm install

ou

user@debian:~% npm i 

Installation d’une dépendance de développement

Si on veut installer un package et indiquer la dépendance sous forme d’une dépendance de développement, il faut exécuter:

npm install <nom du package> --save-dev 

Au lieu de rajouter la dépendance dans l’élément dependencies du fichier package.json, npm rajoutera la dépendance dans l’élément devDependencies.

Pour omettre l’édition de package.json

Pour éviter d’écrire dans le fichier package.json quand on installe un package, il faut ajouter l’argument:

user@debian:~% npm install <nom du package> --no-save 

Installation d’un package dans le répertoire global

Le répertoire global permet de partager un même package parmi plusieurs projets. Pour avoir le préfixe utilisé, il faut exécuter:

user@debian:~% npm config get prefix 

Le répertoire global contenant les packages est <prefixe>/lib/node_modules.

Pour installer un package dans le répertoire global, il faut exécuter:

user@debian:~% npm install --global <nom du package> 

ou

user@debian:~% npm i –g <nom du package> 

Installer une version spécifique

Les instructions précédentes permettent d’installer la dernière version du package toutefois on peut installer une version spécifique:

user@debian:~% npm install <nom du package>@<version du package> 

Par exemple:

user@debian:~% npm install protractor@5.3.0 

Indication de version dans package.json

Par défaut la version est indiquée dans le fichier package.json en utilisant le caractère ^:

{ 
  "name": "test_package", 
  ..., 
  "dependencies": { 
    "protractor": "^5.3.2" 
  } 
} 

Ce caractère permet d’indiquer que npm mettra à jour le package en exécutant npm update en ne considérant que les versions avec le même numéro majeur. Npm utilise le Semantic Versioning avec des numéros de version sous la forme MAJOR.MINOR.PATCH. Ainsi le même numéro majeur signifie dans notre exemple que npm tentera de mettre à jour le package en cherchant des versions de la forme 5.x.y.

Dans le cadre du Semantic Versioning, un changement de version majeure signifie qu’un breaking change a été introduit.

On peut modifier ce comportement en remplaçant le caractère ^ par ~ dans le fichier package.json. Par exemple:

{ 
  "name": "test_package", 
  ..., 
  "dependencies": { 
    "protractor": "~5.3.2" 
  } 
} 

Le caractère ~ permet d’indiquer que npm bloque la version majeure et mineure. Ainsi, le même

Numéro majeur et mineur signifie dans notre exemple que npm tentera de mettre à jour en cherchant des versions de la forme 5.3.x.

Dans le cadre du Semantic Versioning, un changement de version mineure signifie qu’il n’y a pas de breaking changes et qu’une nouvelle fonctionnalité a été rajoutée.

On peut bloquer une version précise en omettant tout caractère devant la version:

{ 
  "name": "test_package", 
  ..., 
  "dependencies": { 
    "protractor": "5.3.2" 
  } 
} 

On peut indiquer à npm d’ajouter un caractère différent de celui par défaut à l’installation d’un nouveau package en exécutant:

user@debian:~% npm config set save-prefix="~"

On peut modifier le comportement par défaut pour bloquer la version d’un package à chaque installation. Il faut exécuter:

user@debian:~% npm config set save-exact true

Utiliser un fichier npm-shrinkwrap.json

Pour figer une version d’un package, on peut utiliser un fichier nommé npm-shrinkwrap.json à ranger dans le répertoire du projet. Depuis la version 5.x.y, ce fichier a été remplacé par le fichier package-lock.json. Le fichier package-lock.json est généré à chaque édition de npm init.

Utiliser npm-shrinkwrap.json est toutefois obsolète.

Si on souhaite vraiment utiliser un fichier npm-shrinkwrap.json, il suffit d’exécuter:

user@debian:~% npm shrinkwrap 
npm notice package-lock.json has been renamed to npm-shrinkwrap.json. npm-shrinkwrap.json 
will be used for future installations. 

Lister les packages installés

Pour lister les packages installés au niveau local, il faut exécuter:

user@debian:~% npm list

ou

user@debian:~% npm ls

Les packages seront listés avec leurs dépendances.

Pour lister les packages sans leurs dépendances:

user@debian:~% npm list --depth=0

Enfin pour lister les packages installés de façon globale:

user@debian:~% npm list --global 

ou

user@debian:~% npm list –g 

On peut afficher d’autres informations en listant les packages:

user@debian:~% npm ll

ou

user@debian:~% npm la

Désintaller un package

Pour désinstaller un package installé localement, il faut exécuter:

user@debian:~% npm uninstall <nom du package> 

ou

user@debian:~% npm un <nom du package> 

Les dépendances seront aussi désinstallées et l’entrée correspondante dans le fichier package.json sera supprimée.

Pour désinstaller un package de façon globale, il faut exécuter:

user@debian:~% npm uninstall --global <nom du package> 

ou

user@debian:~% npm uninstall -g <nom du package> 

Avoir des informations sur un package

On peut avoir des informations sur un package en exécutant:

user@debian:~% npm view <nom du package> 

Pour avoir des informations de version:

user@debian:~% npm view <nom du package>  versions 

Pour voir la page d’accueil du package:

user@debian:~% npm home <nom du package> 

Pour avoir le repository Git:

user@debian:~% npm repo <nom du package> 

Pour avoir de la documentation:

user@debian:~% npm docs <nom du package> 

Pour voir les bugs:

user@debian:~% npm bugs <nom du package> 

Mise à jour d’un package

Afficher les packages à mettre à jour

Pour afficher les packages pour lesquels une nouvelle version existe, il faut exécuter:

user@debian:~% npm outdated

L’affichage se fera de cette façon:

Package     Current  Wanted  Latest  Location 
protractor    5.3.0   5.3.2   5.3.2  test_package 

Effectuer des mises à jour

Pour mettre à jour un package:

user@debian:~% npm update <nom du package>  

ou

user@debian:~% npm up <nom du package> 

Supprimer les packages du cache

A chaque installation d’un package, npm range les packages téléchargés dans le répertoire nommé .npm dans le répertoire home de l’utilisateur. Le répertoire cache est utilisé pour éviter de solliciter le réseau pour réinstaller des packages déjà téléchargés.

Ainsi, le cache se trouve dans le répertoire .npm. Si on liste ce répertoire:

user@debian:~% ls .npm 
anonymous-cli-metrics.json   _cacache   index-v5   _locks   _logs 

Pour supprimer le cache, il faut exécuter la commande:

user@debian:~% npm cache clean

Chercher des packages

Pour chercher des packages se trouvant parmi la liste des packages disponibles, on peut exécuter:

user@debian:~% npm search <nom partiel du package> 

Supprimer des packages non référencés

Certains packages peuvent être installés mais non référencés dans le fichier package.json. Pour supprimer ces packages, on peut exécuter:

user@debian:~% npm prune

Utilisation de scripts

Un des grands intérêts de npm est de pouvoir exécuter des scripts dans le cadre de certaines actions. Pour exécuter un script, il faut exécuter la commande:

user@debian:~% npm run <nom du script> 

ou

user@debian:~% npm run-script <nom du script> 

Pour voir la liste des scripts disponibles, on peut écrire:

user@debian:~% npm run 

ou

user@debian:~% npm run-script 

Certaines actions peuvent être exécutées directement sans forcément utiliser la syntaxe npm run <nom de la commande> ou npm run-script <nom de la commande>.

Par exemple:

• npm install: permet d’installer des packages.
• npm pack: produit un fichier compressé des fichiers à déployer.
• npm publish: publie un package.
• npm restart: exécute les scripts stop et start dans cet ordre sauf si un script spécifique nommé restart est précisé.
• npm start: exécute le script nommé start généralement pour démarrer le serveur Node.js.
• npm stop: exécute le script nommé stop généralement pour stopper le serveur Node.js.
• npm test: permet d’exécuter les tests.
• npm uninstall: désinstalle un ou plusieurs packages.
• npm unpublish: supprime un package qui a été publié.

Les autres scripts doivent être exécutés en utilisant la syntaxe npm run <nom de la commande> ou npm run-script <nom de la commande>.

Le code correspondant aux scripts peut être implémenté dans l’élément de configuration scripts dans le fichier package.json. Par exemple, on peut voir cet élément de configuration dans le fichier généré plus haut (grâce à npm init):

{ 
  "name": "test_package", 
  "version": "1.0.0", 
  "description": "Description du package test_package", 
  "main": "index.js", 
  "scripts": { 
    "test": "echo \"Error: no test specified\" && exit 1" 
  },
  "author": "", 
  "license": "ISC" 
} 

Dans cet exemple, seul le script test est implémenté.

Pour certaines commandes, il n’est pas forcément nécessaire d’implémenter du code pour qu’un traitement soit effectué comme npm install, npm pack, npm publish, npm uninstall et npm unpublish.

npm considère qu’un script qui renvoie 0 a réussi son exécution et à l’opposé, un script qui renvoie 1 a échoué.

"scripts": { 
    "test": "protractor protractor-config.js" 
  } 

Exécution de scripts personnalisés

En plus de tous les scripts décrits plus haut, on peut personnaliser le nom d’un script à exécuter en l’indiquant dans le fichier package.json.
Par exemple, si on nomme un script myscript:

"scripts": { 
    "myscript": "echo 1" 
  } 

On peut appeler ce script directement en utilisant la même syntaxe:

npm run myscript

ou

npm run-script myscript

Dépendances entre les scripts

Pour la plupart des scripts, quand on exécute un script nommé <script>, les scripts suivants seront exécutés s’ils sont implémentés:

• pre<script>: il sera exécuté avant le script <script>.
• post<script>: il sera exécuté après le script <script>.

Si un script dans la suite pre<script>, <script> et post<script> échoue (renvoie 1), l’exécution s’interrompt.

Par exemple, pour la plupart des scripts la règle indiquée précédemment est valable:

• pretest ⇒ test ⇒ posttest
• prestart ⇒ start ⇒ poststart
• prestop ⇒ stop ⇒ poststop
• prerestart ⇒ restart ⇒ postrestart
• preuninstall ⇒ uninstall ⇒ postuninstall

Pour d’autres commandes, le workflow est plus complexe:

• pack: prepublish ⇒ prepare ⇒ prepack ⇒ pack ⇒ postpack
• publish: prepublish ⇒ prepare ⇒ prepublishOnly ⇒ publish ⇒ postpublish
• install (sans arguments supplémentaires): prepublish ⇒ prepare ⇒ preinstall ⇒ install ⇒ postinstall

Ajouter des arguments en exécutant un script

On peut transmettre des arguments à un script directement à partir de la ligne de commande npm. Par exemple, en exécutant:

npm run test -- --grep="pattern" 

Les arguments --grep="pattern" sont transmis au script test qui sera exécuté.

Exécuter des scripts dans des packages

On peut exécuter des scripts présents dans des packages en exécutant la commande:

npm explore <nom du package> -- npm run <nom du script> 

Exemple de configuration des scripts d’un fichier package.json

Dans le cadre d’un projet Typescript, voici un exemple d’implémentation de scripts dans le fichier package.json:

"scripts": { 
  "info": "npm-scripts-info", 
  "build": "run-s clean && run-p build:*", 
  "build:main": "tsc -p tsconfig.json", 
  "build:module": "tsc -p tsconfig.module.json", 
  "fix": "run-s fix:*", 
  "fix:prettier": "prettier \"src/**/*.ts\" --write", 
  "fix:tslint": "tslint --fix --project .", 
  "test": "run-s build test:*", 
  "test:lint": "tslint --project . && prettier \"src/**/*.ts\" --list-different", 
  "test:unit": "nyc --silent ava", 
  "test:nsp": "nsp check", 
  "watch": "run-s clean build:main && run-p \"build:main -- -w\" \"test:unit -- --watch\"", 
  "cov": "run-s build test:unit cov:html && opn coverage/index.html", 
  "cov:html": "nyc report --reporter=html", 
  "cov:send": "nyc report --reporter=lcov > coverage.lcov && codecov", 
  "cov:check": "nyc report && nyc check-coverage --lines 100 --functions 100 --branches 100", 
  "doc": "run-s doc:html && opn build/docs/index.html", 
  "doc:html": "typedoc src/ --target ES6 --mode file --out build/docs", 
  "doc:json": "typedoc src/ --target ES6 --mode file --json build/docs/typedoc.json", 
  "doc:publish": "gh-pages -m \"[ci skip] Updates\" -d build/docs", 
  "version": "standard-version", 
  "reset": "git clean -dfx && git reset --hard && npm i", 
  "clean": "trash build test", 
  "all": "run-s reset test cov:check doc:html", 
  "prepare-release": "run-s all version doc:publish" 
} 

Pour résumer…

Voici un tableau récapitulatif des commandes les plus utiles: