Ce que fait réellement npm install : le registre, package.json et les fichiers de verrouillage

Presque tous les projets JavaScript, qu’ils fonctionnent sous Node.js, React ou Next.js, commencent avec la même commande, et de nombreux développeurs l’exécutent quotidiennement sans vraiment comprendre ce qu’elle fait. Connaître l’origine des paquets, la manière dont npm décide de ce qu’il faut installer, ainsi que la fonction respective de package.json, package-lock.json et node_modules permet de déboguer plus facilement les installations défaillantes. Ce guide aborde chaque aspect, de la première installation jusqu’à la publication de son propre paquet.

Les commandes que tout le monde tape

La forme la plus courante consiste à installer tout ce que le projet a déjà déclaré :

npm install

Il est tout aussi courant d’ajouter une bibliothèque par son nom, comme le framework web Express :

npm install express

ou le client HTTP Axios :

npm install axios

Derrière ces lignes uniques se posent plusieurs questions. D’où le code est-il téléchargé ? Comment npm sait-il sur quels éléments dépend un projet ? À quoi sert package.json ? Et pourquoi node_modules devient-il si volumineux ?

Qu’est-ce que npm

npm est le gestionnaire de paquets par défaut pour Node.js et fait partie intégrante de ce dernier. Il vous donne accès à un vaste catalogue de paquets réutilisables publiés par d’autres développeurs, vous permettant ainsi d’intégrer du code éprouvé dans votre projet au lieu de le coder vous-même.

Pensez-y comme à une bibliothèque publique de code. Supposons qu’un backend Node.js ait besoin d’un serveur HTTP. Plutôt que de développer le routage et les middlewares depuis zéro, vous ajoutez Express :

npm install express

Vous devez appeler d’autres APIs ? Ajoutez un client HTTP :

npm install axios

La validation des données entrantes selon un schéma est gérée par Zod :

npm install zod

Bcrypt s’occupe du hachage des mots de passe :

npm install bcrypt

C’est la plus grande force de cet écosystème : lorsqu’une solution bien testée existe, il y a rarement de raison d’en créer une soi-même. D’un autre côté, chaque package installé est du code en qui on doit avoir confiance ; il convient donc de privilégier des bibliothèques maintenues et largement utilisées, tout en gardant la liste concise. Consultez comment fonctionnent les attaques sur la chaîne d’approvisionnement de npm pour comprendre l’importance de cela.

Un écosystème, pas seulement une commande

Les nouveaux venus voient souvent npm comme un simple mot saisi dans la terminal. En réalité, ce nom désigne plusieurs composants qui coopèrent entre eux :

• Le registre npm : le service public où les packages sont publiés et téléchargés.
• La CLI npm : l’outil en ligne de commande qui communique avec le registre et gère les dépendances.

Pakets : les unités de code réutilisables elles-mêmes.

package.json : le manifeste qui décrit votre projet et ses dépendances.

Les pakets publics sont gratuits : vous pouvez installer n’importe quel package public sans compte. Ce faible obstacle a contribué à la diffusion mondiale du JavaScript open source. Un compte n’est nécessaire que pour publier.

Que se passe-t-il lorsque vous exécutez npm install

Prenons un projet qui ajoute Express :

npm install express

À un niveau général :

1. npm recherche le package dans le registre et choisit une version correspondant à la plage demandée (la dernière si aucune n’est indiquée).
2. Il résout les dépendances du package lui-même, ainsi que celles de ces dernières, pour former un arbre complet.
3. Il télécharge tout ce qui n’est pas déjà en cache et le place dans node_modules.

Il enregistre la dépendance dans package.json ainsi que l’arborescence résolue exacte dans package-lock.json.

C’est ainsi qu’un seul commandement simple permet d’obtenir toute une série de fonctionnalités.

package.json : le manifeste du projet

Un fichier se trouve au cœur de chaque projet Node.js :

package.json

Il agit à la fois comme la carte d’identité et la configuration de votre projet, contenant le nom, la version, la description, les scripts, les dépendances en temps de exécution et en développement, ainsi que les informations sur l’auteur. Un exemple minimal définit un fichier d’entrée sous le nom main, un script et une seule dépendance :

{
  "name": "my-project",
  "version": "1.0.0",
  "description": "My Node.js application",
  "main": "index.js",
  "scripts": {
    "start": "node index.js"
  },
  "dependencies": {
    "express": "^5.1.0"
  }
}

name

name identifie le projet ou le package. Si vous le publiez, c’est ce que les gens saisissent pour l’installer ; il doit donc être unique dans le registre.

"name": "my-project"

version

version indique la version actuelle du package.

"version": "1.0.0"

Cela est particulièrement important lors de la publication. npm utilise une versionnement sémantique (MAJOR.MINOR.PATCH) : les changements perturbateurs augmentent le numéro majeur, les fonctionnalités compatibles celui du mineur, et les correctifs celui du patch.

description

description est un résumé en une ligne de ce que fait le projet, affiché dans les résultats de recherche du registre.

"description": "My Node.js application"

scripts

scripts définit des raccourcis nommés pour les commandes fréquentes. Ici, start lance le fichier d’entrée :

"scripts": {
  "start": "node index.js"
}

Sans cela, vous devriez taper la commande complète :

node index.js

Avec cela, ceci fait la même chose :

npm start

La valeur réside dans la cohérence : chaque contributeur et chaque job CI exécute la même commande nommée. Les noms personnalisés tels que build s’exécutent avec npm run build.

Dépendances : de quoi dépend votre projet

Imaginez une plateforme de livraison de nourriture. Son backend pourrait utiliser :

• Express pour les APIs
• Zod pour la validation
• bcrypt pour le hachage des mots de passe
• une bibliothèque JSON Web Token pour l’authentification
• Mongoose pour MongoDB

Chacun d’eux constitue une dépendance. Lorsque vous en installez une :

npm install express

npm ajoute une entrée dans package.json :

"dependencies": {
  "express": "^5.1.0"
}

Le symbole caret dans ^5.1.0 indique une plage : toute version 5.x ultérieure est acceptée, mais 6.0.0 ne l’est pas. Cette entrée indique à quiconque consulte le projet que celui-ci a besoin d’Express pour fonctionner. Les outils nécessaires uniquement pendant le développement, tels que les exécutateurs de tests, sont placés dans devDependencies via npm install --save-dev.

Pourquoi une seule commande s’adapte à toute une équipe

Supposons que vous rejoigniez une équipe et que vous cloniez son répertoire. Personne ne s’attend à ce que vous téléchargiez manuellement cinquante bibliothèques. Vous exécutez :

npm install

npm lit les dépendances déclarées et les installe toutes. C’est en reconstruisant un environnement de travail à partir d’une description que les gestionnaires de paquets deviennent indispensables.

node_modules : où se trouve le code installé

Après une installation, un nouveau dossier apparaît :

node_modules/

Il contient les paquets que vous avez demandés ainsi que tout ce dont ils dépendent, d’où sa taille importante. Une structure typique :

my-project/
│
├── node_modules/
├── package.json
├── package-lock.json
└── index.js

Ne commitez pas node_modules dans Git. Il est volumineux, peut contenir des versions spécifiques à une plateforme et peut toujours être regénéré. Mettez-le dans .gitignore et commitez plutôt ceci :

package.json
package-lock.json

N’importe qui peut alors exécuter :

npm install

et obtenir à nouveau les mêmes dépendances.

package-lock.json : le registre exact

Un deuxième fichier se trouve à côté du manifeste :

package-lock.json

Pourquoi les deux ? En version courte :

• package.json indique ce dont a besoin le projet, généralement sous forme de plages.
• package-lock.json enregistre précisément ce qui a été installé : chaque version de package dans l’ensemble du arborescence, ainsi que les hachages d’intégrité.

Puisque les plages peuvent correspondre à des versions plus récentes avec le temps, le fichier de verrouillage permet aux ordinateurs portables, aux collègues et aux systèmes CI d’utiliser des versions identiques. Committez-le, et préférez npm ci dans les systèmes CI, qui installe strictement à partir du fichier de verrouillage.

Commandes npm à connaître

Ajouter un package :

npm install express

Installer tout ce que le projet déclare :

npm install

Supprimer un package de node_modules et de package.json :

npm uninstall express

Mettre à jour les packages aux versions les plus récentes autorisées par les plages (cela n’entrera pas dans une nouvelle version majeure) :

npm update

Afficher la version de npm :

npm -v

Afficher la version de Node.js :

node -v

Montrer le compte npm sous lequel vous êtes connecté :

npm whoami

De consommateur à éditeur

npm install your-package

Cette boucle maintient le logiciel open source en vie : vous construisez sur le travail des autres, créez le vôtre et le partagez à nouveau.

Étapes de publication pas à pas

npm login

Confirmer quel compte est actif :

npm whoami

Se rendre dans le projet :

cd myproject

Vérifier qu’il dispose d’un manifeste valide avec un name unique et une version :

package.json

Puis publier :

npm publish

Le paquet est désormais accessible à tous. Deux conseils : exécutez d’abord npm pack --dry-run pour voir quels fichiers seront inclus, et augmentez la version à chaque publication, car une version publiée ne peut pas être réutilisée. Consultez la documentation actuelle de npm pour connaître les exigences en matière de sécurité des comptes, telles que l’authentification à deux facteurs.

Comment les éléments s’assemblent

Tout le processus se déroule comme suit :

Developer
    ↓
npm install
    ↓
npm Registry
    ↓
Package + Dependencies
    ↓
node_modules
    ↓
package.json
    ↓
Your Application

Vous exécutez la commande, l’interface en ligne de commande récupère les paquets depuis le registre, le code est stocké dans node_modules, le manifeste et le fichier de verrouillage enregistrent ces informations, et votre application l’importe. C’est cette chaîne qui permet aux développeurs de réutiliser, gérer, partager et publier du code efficacement.

Points clés

Npm peut sembler être un ensemble de commandes en terminal, mais une fois que vous comprenez ce qui se passe derrière :

npm install

Le système devient facile à comprendre. JavaScript fournit le langage, Node.js l’environnement d’exécution, et npm l’écosystème pour partager du code. En pratique :

• package.json déclare l’intention ; package-lock.json enregistre la réalité. Committez les deux.
• N’committez jamais node_modules.
• Une plage de caret permet des mises à jour mineures et des correctifs, et npm update reste dans cette plage.
• Utilisez npm ci pour des installations précises dans les processus automatisés.
• Ajoutez des dépendances de manière intentionnelle ; chacune d’elles représente du code en qui vous avez confiance.

Ainsi, la prochaine fois que vous taperez :

npm install

rappelez-vous que vous reliez votre projet à un écosystème créé par des développeurs du monde entier.

Lectures complémentaires

• Ce que JSON.stringify omet secrètement, transforme et refuse de serialiser — Découvrez quels valeurs JavaScript JSON.stringify ignore ou modifie, comment toJSON, les remplaçants et les réanimateurs y remédient, et quand structuredClone est l’outil le plus adapté.
• Ce que async/await garantit réellement, et ce qu’il laisse aux utilisateurs — Comprenez ce que await suspend réellement, comment éviter les requêtes serialisées, et pourquoi les erreurs, la cancellation, l’ordre des exécutions et les tentatives de réessai nécessitent des solutions allant au-delà d’async/await.