Gérer les dépendances Node.js

Les dépendances sont du code que vous n'avez pas écrit, mais que vous exécutez avec vos droits et vos données. Une version qui dérive entre votre machine et la plateforme suffit à provoquer un bug impossible à reproduire. La maîtrise des dépendances repose sur trois éléments : les portées de version, le lockfile et une mise à jour testée.

Portées de version

Dans package.json :

{
  "dependencies": {
    "express": "^4.19.2",
    "pg": "~8.11.5"
  },
  "devDependencies": {
    "typescript": "5.5.4"
  },
  "engines": {
    "node": ">=22"
  }
}

• ^4.19.2 accepte les versions mineures et correctives, pas une majeure.
• ~8.11.5 accepte les correctifs uniquement.
• 5.5.4 fige une version exacte.
• latest ou * rend le déploiement non reproductible.

dependencies sert au runtime, devDependencies aux outils de build et de test. Un paquet utilisé au démarrage mais placé dans devDependencies disparaît avec npm ci --omit=dev.

Le lockfile est le contrat

package-lock.json enregistre l'arbre exact des versions. Commitez-le. npm ci installe cet arbre, supprime node_modules et échoue si package.json et le lockfile divergent ; c'est la commande de déploiement. npm install met à jour le lockfile et peut changer des versions transitives.

Ne modifiez pas le lockfile à la main. S'il est absent, générez-le, testez, puis commitez-le. Un lockfile généré sous Windows reste valable sous Linux, sauf modules natifs.

Auditer et mettre à jour

npm outdated
npm audit
npm update

npm outdated liste les écarts entre installé, souhaité et dernière version. npm audit signale les vulnérabilités connues ; npm audit fix corrige dans les portées autorisées, tandis que --force peut casser une majeure. Lisez le changelog avant une montée de version majeure, mettez à jour un paquet à la fois et testez le démarrage ainsi qu'un parcours critique.

Les bots de mise à jour (Dependabot, Renovate) réduisent l'oubli, à condition de regrouper les correctifs et de ne pas fusionner sans test.

Modules natifs

sharp, bcrypt ou canvas compilent du code natif. Ils dépendent de la bibliothèque C du système et de l'architecture. Un binaire précompilé peut ne pas correspondre au conteneur, et vous n'avez pas root pour installer les outils de compilation. Préférez une alternative pure JavaScript (bcryptjs), une version avec prebuilds, ou testez l'installation sur la plateforme avant de l'adopter. Une erreur node-gyp est un problème d'environnement, pas de syntaxe.

Vérifier

Après une mise à jour : npm ci, démarrage, route de santé, accès base, et lecture des journaux. Supprimez les paquets inutilisés (npm ls aide à repérer les doublons). Gardez la version de Node déclarée dans engines cohérente avec le runtime choisi.