Comprendre package.json et npm

3 min de lecture07 novembre 2026

package.json est le manifeste que npm et la plateforme lisent pour savoir comment installer et démarrer votre application. Un fichier approximatif produit des déploiements qui marchent sur votre machine et échouent ailleurs. Les champs réellement utiles sont peu nombreux, mais chacun a un effet concret.

Les champs qui comptent

JSON

{
  "name": "mon-app",
  "version": "1.4.0",
  "private": true,
  "main": "index.js",
  "scripts": {
    "start": "node index.js",
    "build": "node build.js"
  },
  "engines": {
    "node": ">=20 <25"
  },
  "dependencies": {
    "express": "^5.1.0"
  },
  "devDependencies": {
    "eslint": "^9.0.0"
  }
}

name et version identifient le projet ; private: true empêche une publication accidentelle sur le registre npm.
main indique le fichier d'entrée ; il doit correspondre au fichier réel.
scripts contient les commandes nommées, appelées avec npm run nom ou npm start.
engines documente la version de Node.js attendue ; elle est indicative sauf si engine-strict est activé.
dependencies liste ce qui est nécessaire à l'exécution.
devDependencies liste les outils de développement, absents en production.

Dépendances et versions

npm install express ajoute la bibliothèque à dependencies et met à jour le fichier de verrouillage. Les symboles de version contrôlent les mises à jour acceptées :

Notation	Accepte	Usage
`^5.1.0`	correctifs et mineures `5.x`	défaut, compromis courant
`~5.1.0`	correctifs `5.1.x`	évolution plus lente
`5.1.0`	cette version exacte	dépendance critique

Une dépendance utilisée uniquement au moment du build ou des tests va dans devDependencies (npm install --save-dev). Si elle est requise au démarrage, elle va dans dependencies : sinon elle manquera en production.

Scripts et commande de démarrage

Bash

npm start
npm run build
npm run

npm start exécute le script start, ou node server.js par défaut si le script est absent. La plateforme peut aussi lancer directement node index.js : le script et le fichier principal doivent donc désigner le même point d'entrée.

Le fichier de verrouillage

npm install résout les plages de versions et écrit package-lock.json, qui fige l'arbre complet des dépendances. Versionnez ce fichier : sans lui, deux installations peuvent produire des versions différentes.

Commande	Effet	Quand l'utiliser
`npm install`	met à jour `package.json` et le lockfile, peut changer des versions	développement, ajout d'une dépendance
`npm ci`	supprime `node_modules`, installe exactement le lockfile	déploiement, intégration continue

npm ci échoue si package.json et le lockfile ne sont pas synchronisés : c'est une protection, pas un bug. Corrigez le lockfile avec npm install en local, puis relancez.

Erreurs courantes

Un module fonctionne en local parce qu'il est installé globalement : déclarez-le dans dependencies.
npm ci échoue sans package-lock.json : versionnez le fichier.
Un module natif compilé sur macOS ne tourne pas sur Linux : réinstallez-le sur la plateforme.
Une dépendance de build manque en production parce qu'elle est dans devDependencies.
engines n'est pas respecté : vérifiez la version choisie dans le panneau et restez dans une plage supportée.

Un package.json lisible et un lockfile versionné suffisent à rendre un déploiement Node.js reproductible.