npm : install, init, update et gestion des dépendances

npm, c'est quoi au juste

Derrière le nom npm, il y a en réalité trois choses. D'abord un registre : une immense base de données publique de paquets JavaScript, hébergée sur npmjs.com. Ensuite un outil en ligne de commande, livré avec Node.js, qui sert à installer et gérer ces paquets. Et enfin une spécification — le format package.json — qui décrit ce dont un projet a besoin pour fonctionner.

Quand tu lances npm install express, la CLI interroge le registre, télécharge express ainsi que toutes ses dépendances, pose les fichiers dans un dossier node_modules et note le paquet avec sa version dans ton package.json. Voilà toute la mécanique.

Si Node.js est déjà installé sur ta machine, tu as npm aussi. Pour vérifier :

node --version
npm --version

Si les deux affichent une version, tu es prêt.

Démarrer un projet : npm init

Chaque projet npm a besoin d'un fichier package.json. C'est le manifeste du projet : on y retrouve le nom, la version, les scripts et les dépendances. Le moyen le plus rapide d'en générer un, c'est npm init -y, qui accepte toutes les valeurs par défaut :

mkdir my-app
cd my-app
npm init -y

That writes something like :

{
  "name": "my-app",
  "version": "1.0.0",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [],
  "author": "",
  "license": "ISC"
}

Si tu omets le -y, npm te pose les questions une par une pour chaque champ. Dans les deux cas, tu obtiens un package.json — le fichier auquel tout le reste va se rattacher. On verra ses champs en détail sur la page suivante.

Installer un package avec npm install

Une fois que tu as ton package.json, installe un package avec npm install (ou npm i, en version courte) :

npm install lodash

Trois choses se produisent :

1. npm télécharge lodash et ses dépendances dans node_modules/.
2. Il ajoute "lodash": "^4.17.21" (ou la version la plus récente) dans la section dependencies du fichier package.json.
3. Il génère un fichier package-lock.json qui consigne les versions exactes de chaque paquet de l'arborescence.

Tu peux désormais t'en servir :

L'appel à require (ou import dans un projet ESM) retrouve le package en fouillant dans node_modules. Pas besoin d'indiquer un chemin — le résolveur de modules de Node s'en occupe tout seul.

dependencies vs devDependencies

Tous les packages ne sont pas utiles quand l'application tourne en production. Les frameworks de test, les linters ou encore les bundlers ne servent qu'en phase de développement. Pour ceux-là, on installe avec --save-dev (ou -D) :

npm install --save-dev jest
npm install -D eslint prettier

Ces paquets atterrissent dans devDependencies plutôt que dans dependencies :

{
  "dependencies": {
    "lodash": "^4.17.21"
  },
  "devDependencies": {
    "jest": "^29.7.0",
    "eslint": "^8.57.0",
    "prettier": "^3.2.5"
  }
}

Sur un serveur de production, npm install --omit=dev ignore totalement la section dev, ce qui rend l'installation plus légère et plus rapide. Bien gérer cette répartition est plus important qu'on ne le croit — un webpack mal placé dans les dependencies alourdit inutilement chaque déploiement en prod.

Tout installer d'un coup avec npm install

Quand tu clones un dépôt qui contient déjà un package.json, pas besoin d'énumérer chaque paquet. Il suffit de lancer :

npm install

Sans aucun argument, npm lit le fichier package.json (en respectant scrupuleusement les versions figées dans package-lock.json) et installe tout l'arbre de dépendances dans node_modules. C'est la toute première commande à lancer après avoir cloné un projet.

D'ailleurs, c'est aussi pour ça que node_modules doit figurer dans le .gitignore. Le dossier est reproductible à partir du lockfile, il est énorme, et son contenu change à chaque npm install. On versionne donc package.json et package-lock.json, et chacun régénère son node_modules de son côté.

Mettre à jour les paquets

La commande npm outdated liste les paquets en retard :

npm outdated

Tu verras apparaître un tableau avec les colonnes Current, Wanted et Latest. Wanted, c'est la version la plus récente autorisée par la plage définie dans ton package.json (avec ^4.17.21, tout ce qui reste sous 5.0.0). Latest, c'est la dernière version publiée sur npm, qui peut être une version majeure à laquelle tu n'as pas encore souscrit.

Pour mettre à jour dans la plage autorisée :

npm update

Pour sauter directement à la toute dernière version, y compris les changements de version majeure, réinstalle le paquet avec @latest :

npm install lodash@latest

Un changement de version majeure peut casser ton code — c'est précisément ce que ce numéro veut te signaler. Jette un œil au changelog avant de franchir le pas.

Désinstaller un paquet

Supprimer un paquet, c'est l'opération inverse :

npm uninstall lodash

Ça supprime le paquet du dossier node_modules et retire la ligne correspondante dans package.json. Ajoute -D s'il s'agissait d'une dépendance de développement (npm s'en sort tout seul, mais autant être explicite pour éviter les mauvaises surprises dans tes scripts).

Installation globale ou locale ?

Dans la quasi-totalité des cas, tu veux une installation locale — rattachée à un seul projet, dans son node_modules. La seule vraie exception, ce sont les outils en ligne de commande que tu veux pouvoir lancer depuis n'importe où :

npm install -g typescript
npm install -g http-server

Une installation globale place l'outil dans un emplacement système et ajoute son entrée bin à votre PATH, ce qui vous permet de lancer tsc ou http-server depuis n'importe quel dossier. Le souci, c'est que les installations globales ne sont pas suivies projet par projet et peuvent finir par diverger d'une machine à l'autre.

Pour les commandes ponctuelles, npx (livré avec npm) offre un bon compromis :

npx create-react-app my-app
npx prettier --write .

npx permet d'exécuter un paquet sans l'installer globalement — il le récupère à la volée, le lance, et voilà. Pour les outils qu'on n'utilise qu'une seule fois, c'est bien plus propre qu'une installation globale permanente.

Le pense-bête minimal

Les commandes que tu vas vraiment utiliser au quotidien :

npm init -y                     # créer package.json
npm install                     # installer tout ce qui est dans package.json
npm install <pkg>               # ajouter une dépendance d'exécution
npm install -D <pkg>            # ajouter une dépendance de développement
npm install -g <pkg>            # installer un outil CLI globalement
npm uninstall <pkg>             # retirer une dépendance
npm outdated                    # voir ce qui est obsolète
npm update                      # mettre à jour dans les plages autorisées
npm install <pkg>@latest        # passer à la dernière version
npm run <script>                # exécuter un script de package.json
npx <pkg>                       # exécuter un paquet sans l'installer

C'est à peu près tout ce qu'il y a à savoir sur npm. Le reste — la publication, les workspaces, les packages scoped — tu le découvriras le jour où tu en auras besoin.

Ce qu'il y a vraiment dans node_modules

Un dernier modèle mental à avoir en tête. node_modules, c'est un dossier quasi plat qui contient tous les packages dont dépend ton projet, plus tout ce dont ces packages dépendent à leur tour, en cascade. Tu installes un seul package et tu peux en récupérer une centaine au passage — c'est normal. npm déduplique quand il le peut : si deux packages dépendent de la même version de lodash, ils partagent la même copie.

Le fichier de lock (package-lock.json) enregistre la version exacte résolue pour chacun de ces packages. C'est ce qui rend les builds reproductibles : deux développeurs qui lancent npm install à partir du même lockfile obtiennent des arborescences identiques au bit près, même plusieurs mois plus tard.

Considère node_modules comme un dossier généré. Ne modifie jamais les fichiers à l'intérieur — tes changements disparaîtront dès le prochain install de n'importe qui.

La suite : package.json

package.json, c'est le fichier que npm ne cesse de relire et de réécrire en coulisses. Maîtriser ses champs — scripts, main, type, les plages de versions, engines — c'est ce qui transforme npm de boîte noire en outil que tu pilotes vraiment. On attaque ça tout de suite.