Node.js : npm, commandes essentielles

npm est le gestionnaire de paquets fourni avec Node.js. Les exemples utilisent des noms génériques.

Créer un projet

mkdir monprojet && cd monprojet
npm init -y                      # crée package.json avec les valeurs par défaut
npm pkg set type=module          # utilise les modules ES

Le fichier `package.json`

{
  "name": "monprojet",
  "version": "1.0.0",
  "private": true,
  "type": "module",
  "scripts": {
    "start": "node src/serveur.js",
    "dev": "node --watch src/serveur.js",
    "test": "node --test"
  },
  "dependencies": {
    "express": "^5.0.0"
  },
  "devDependencies": {
    "eslint": "^9.0.0"
  },
  "engines": {
    "node": ">=22"
  }
}

Champ	Rôle
`name`, `version`	Identité du projet
`private`	`true` : empêche une publication accidentelle sur npm
`type`	`module` (ES modules) ou `commonjs`
`scripts`	Commandes lancées avec `npm run`
`dependencies`	Paquets nécessaires à l’exécution
`devDependencies`	Paquets de développement (tests, lint, compilation)
`engines`	Versions de Node.js compatibles

Installer et supprimer des paquets

npm install                       # installe tout ce que package.json déclare
npm install express               # ajoute une dépendance
npm install -D eslint             # ajoute une dépendance de développement
npm install express@5.0.0         # version précise
npm install -g typescript         # installation globale (outil en ligne de commande)
npm uninstall express             # supprime

Reproductible : `npm ci`

npm ci                            # installation exacte depuis package-lock.json
npm ci --omit=dev                 # sans les dépendances de développement (production)

npm ci supprime node_modules puis installe exactement les versions de package-lock.json : à utiliser en intégration continue et en production. Le fichier package-lock.json doit être versionné.

Scripts

npm run dev                       # exécute le script « dev »
npm start                         # raccourci pour « start »
npm test                          # raccourci pour « test »
npm run build -- --verbose        # transmet des options après --
npm run                           # liste les scripts disponibles

`npx` : exécuter un outil sans l’installer

npx eslint .                      # utilise la version du projet, ou la télécharge
npx --yes serve ./public          # télécharge et exécute sans confirmation

Versions et mises à jour

Dans package.json, la plage de versions suit le semver (majeur.mineur.correctif) :

Écriture	Autorise
`^1.4.2`	`1.4.2` jusqu’à `1.x.x` (pas de changement majeur)
`~1.4.2`	`1.4.2` jusqu’à `1.4.x`
`1.4.2`	exactement cette version

npm outdated                      # paquets pour lesquels une version plus récente existe
npm update                        # met à jour dans les plages autorisées
npm install express@latest        # passe à la dernière version (y compris majeure)
npm ls --depth=0                  # paquets installés (niveau 1)
npm ls express                    # où un paquet est utilisé
npm view express versions         # versions disponibles
npm view express version          # dernière version

Sécurité

npm audit                         # vulnérabilités connues dans les dépendances
npm audit fix                     # corrige sans changement majeur
npm audit --omit=dev              # uniquement les dépendances de production
npm ci --ignore-scripts           # n'exécute pas les scripts d'installation des paquets

Configuration

npm config list                   # configuration active
npm config get prefix             # dossier des installations globales
npm config set prefix ~/.npm-global
npm config set fund false         # supprime les messages de financement

Un fichier .npmrc à la racine du projet applique des réglages au projet :

save-exact=true                   # écrit les versions exactes dans package.json
engine-strict=true                # refuse d'installer avec une version de Node.js incompatible

Cache et dépannage

npm cache verify                  # vérifie le cache
npm cache clean --force           # vide le cache
rm -rf node_modules package-lock.json && npm install   # réinstallation complète (dernier recours)

Symptôme	Piste
`EACCES` à l’installation globale	Configurer un dossier global personnel (voir Installation)
`ERESOLVE` (conflit de dépendances)	Lire le message : mettre à jour un des paquets ; `--legacy-peer-deps` en dernier recours
Modifications ignorées	Supprimer `node_modules` et relancer `npm ci`
`engine` incompatible	Utiliser la version de Node.js demandée (voir nvm)

Publier un paquet (aperçu)

npm login
npm pack --dry-run                # liste les fichiers qui seraient publiés
npm publish --access public

Pour aller plus loin

Documentation officielle : docs.npmjs.com
Alternative : Gestionnaires de paquets : pnpm et Yarn

Dans la même rubrique