npm

Qu’est-ce que npm ?

npm est le gestionnaire de paquets par défaut pour JavaScript et le plus grand registre de logiciels au monde. Il est fourni avec Node.js, installe les dépendances déclarées dans votre projet, résout leurs versions et vous offre un exécuteur de tâches cohérent via des scripts.

Presque tous les projets JavaScript dépendent de npm, même s’ils utilisent un client différent en arrière-plan. Comprendre son fonctionnement réel — la résolution des versions, l’utilité du lockfile et la raison pour laquelle la CI utilise une commande différente — permet d’éliminer toute une catégorie d’erreurs déroutantes.

package.json

Le manifeste décrit votre projet. Il contient les métadonnées, les dépendances et les scripts.

{
  "name": "my-app",
  "version": "1.0.0",
  "private": true,
  "type": "module",
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "test": "vitest run",
    "lint": "eslint ."
  },
  "dependencies": {
    "react": "^19.0.0",
    "react-dom": "^19.0.0"
  },
  "devDependencies": {
    "vite": "^6.0.0",
    "vitest": "^3.0.0"
  }
}

dependencies sont nécessaires à l’exécution ; devDependencies sont des outils utilisés pour le développement et le build. Le flag private empêche la publication accidentelle, et type: "module" permet d’utiliser les modules ES.

Plages de versions

npm utilise le versionnage sémantique : major.minor.patch. Une plage dans package.json décrit les mises à jour que vous acceptez.

Le caret est le choix par défaut et le plus judicieux pour la plupart des dépendances. Les versions exactes bloquent les corrections de bugs et les patchs de sécurité, alors que le lockfile garantit déjà la reproductibilité.

Le lockfile

package-lock.json enregistre la version exacte et le hash d’intégrité de chaque package de l’arbre, y compris les dépendances transitives.

• Committez-le dans votre gestionnaire de version.
• Ne le modifiez jamais à la main.
• Régénérez-le délibérément lorsque vous souhaitez effectuer une mise à jour.
• Laissez-le être la source unique de vérité pour les versions installées.

Sans lockfile, deux installations du même package.json peuvent produire des arbres différents, et un bug qui n’apparaît qu’en production devient presque impossible à reproduire.

Installation des dépendances

Les deux principales commandes d’installation ont des objectifs différents.

# development: resolve ranges, may update the lockfile
npm install

# CI and clean environments: exact install from the lockfile
npm ci

# add a runtime dependency
npm install zod

# add a development tool
npm install -D vitest

npm ci supprime node_modules, installe strictement à partir du lockfile et échoue si package.json et le lockfile ne sont pas en accord. Cela rend l’opération plus rapide et plus sûre en CI. Utilisez npm install localement lorsque vous modifiez des dépendances.

Scripts

Les scripts sont des commandes nommées exécutées via npm run. C’est ainsi qu’un projet expose une interface cohérente pour tout le monde, y compris pour la CI.

npm run dev
npm run build
npm test        # shorthand for npm run test

Les scripts peuvent appeler des binaires locaux directement, ainsi "dev": "vite" fonctionne sans installation globale. Ils sont également composables : un script ci peut exécuter lint, test et build dans l’ordre. Le fait de conserver ces commandes dans package.json évite à chacun de devoir mémoriser l’invocation exacte.

npx et les workspaces

npx permet d’exécuter le binaire d’un package sans installation globale, ce qui est idéal pour les outils ponctuels.

npx create-vite@latest my-app
npx eslint .

Les Workspaces permettent à un seul dépôt de contenir plusieurs packages partageant un unique node_modules et un fichier lockfile.

{
  "workspaces": ["packages/*", "apps/*"]
}

npm lie les packages entre eux, permettant ainsi à un workspace de dépendre d’un package frère sans avoir à le publier. Pour les monorepos plus volumineux, des outils comme Turborepo ajoutent une couche de mise en cache et d’orchestration des tâches.

Sécurité et maintenance

npm inclut une commande audit qui vérifie votre arbre de dépendances pour détecter d’éventuelles vulnérabilités connues.

npm audit
npm audit fix
npm outdated

Effectuez des audits régulièrement et analysez les résultats plutôt que de lancer aveuglément fix, ce qui pourrait introduire des changements incompatibles (breaking changes). npm outdated indique quelles dépendances disposent de versions plus récentes, ce qui vous permet de planifier vos mises à jour au lieu de les laisser s’accumuler.

Bonnes pratiques

• Commitez package-lock.json et ne le modifiez jamais manuellement.
• Utilisez npm ci dans la CI et npm install uniquement lors de la modification des dépendances.
• Séparez bien les dependencies et les devDependencies.
• Privilégiez les plages de versions avec le caret (^) et laissez le lockfile fixer les versions exactes.
• Définissez des scripts pour chaque tâche courante.
• Exécutez npm audit et npm outdated de manière planifiée.
• Utilisez les workspaces pour les monorepos plutôt que des dépôts séparés.

Erreurs courantes

• Supprimer le lockfile pour « corriger » des problèmes d’installation.
• Exécuter npm install en CI et obtenir des builds non reproductibles.
• Placer des outils de build dans dependencies et alourdir les installations de runtime.
• Ignorer les avertissements d’audit jusqu’à ce qu’ils deviennent urgents.
• Installer des packages globalement alors que npx ou une devDependency suffiraient.
• Modifier node_modules en s’attendant à ce que le changement persiste.

Et après ?

npm est le socle de la chaîne d’outils JavaScript. Comparez-le à pnpm pour gagner en vitesse et en efficacité disque, familiarisez-vous avec le runtime Node.js qui l’accompagne, et ajoutez Turborepo lorsque votre dépôt évolue vers un monorepo. Enfin, nettoyez les scripts de votre projet afin que toute l’équipe partage un ensemble de commandes unique.