npm-check-updates : maîtrisez vos dépendances JavaScript

En résumé : Au 5 septembre 2026, utilisez npm-check-updates pour décider et écrire les nouvelles versions dans package.json, puis votre gestionnaire de paquets pour installer et verrouiller ces versions. Préférez npm outdated pour un simple diagnostic. Pour les mises à jour majeures, procédez dépendance par dépendance et validez chaque changement par les tests.

npm update respecte les contraintes semver déjà déclarées. npm-check-updates, ou ncu, répond à un autre besoin : repérer les versions situées au-delà de ces contraintes et préparer explicitement leur adoption.

npm-check-updates ou npm outdated : lequel choisir ?

Les outils sont complémentaires, pas interchangeables.

Commande	Usage principal	Modifie le projet
npm outdated	Comparer les versions installées, « wanted » et « latest »	Non
npm update	Installer les versions autorisées par les contraintes actuelles	Oui, dans les limites semver
ncu	Afficher les nouvelles versions possibles pour package.json	Non
ncu -u	Réécrire les versions déclarées dans package.json	Oui, sans installation

La documentation officielle de npm précise que npm outdated distingue notamment la version installée, la plus haute version compatible avec la contrainte et la version associée au tag latest. De son côté, la documentation de npm-check-updates indique que ncu ignore les numéros actuellement déclarés tout en conservant leur politique semver, par exemple l’opérateur ^.

Comment lancer ncu sans l’installer ?

La forme la plus simple avec npm utilise le nom complet du paquet :

npx npm-check-updates

Vous pouvez aussi l’installer globalement :

npm install -g npm-check-updates
ncu

Par défaut, la commande affiche les propositions. Pour réécrire package.json, ajoutez -u :

ncu -u
npm install
npm test

Cette séparation est essentielle. ncu -u prépare les déclarations ; npm install résout les versions, met à jour node_modules et le lockfile. Contrôlez le diff avant de valider.

Comment limiter le niveau des mises à jour ?

L’option --target permet d’éviter une montée générale vers les versions latest :

# Correctifs uniquement
ncu --target patch

# Versions mineures et correctifs, sans changer de majeure
ncu --target minor

# Rester dans les contraintes semver déclarées
ncu --target semver

Selon la spécification Semantic Versioning, une version majeure signale des changements incompatibles de l’API publique. Cette convention guide l’analyse, mais elle ne remplace ni les notes de version ni les tests du projet.

Comment sélectionner les dépendances à mettre à jour ?

Le mode interactif convient à une sélection manuelle :

ncu --interactive

Pour cibler ou exclure des paquets dans un script, utilisez les filtres :

# Cibler React et React DOM
ncu -u --filter "react react-dom"

# Exclure TypeScript et ESLint
ncu -u --reject "typescript eslint"

Vous pouvez également limiter la recherche à certaines sections de package.json :

ncu --dep prod
ncu --dep dev

Comment réussir une mise à jour majeure ?

Une mise à jour majeure mérite un changement isolé. Le workflow recommandé est volontairement sobre :

# Examiner une seule dépendance
ncu --filter express

# Mettre à jour sa déclaration
ncu -u --filter express

# Installer, puis vérifier le projet
npm install
npm test

Lisez ensuite le guide de migration du paquet et vérifiez le diff du lockfile. Évitez de mélanger plusieurs migrations majeures : si un test casse, vous identifierez plus vite la cause.

Pour une analyse automatisée, le mode docteur installe les mises à jour et lance les tests afin d’identifier celles qui cassent le projet :

ncu --doctor -u --doctorInstall "npm install" --doctorTest "npm test"

Ce mode modifie aussi le lockfile et node_modules. Lancez-le uniquement sur un état versionné et propre.

Comment réduire le risque lié aux versions très récentes ?

L’option --cooldown impose un âge minimal aux versions proposées :

ncu --cooldown 7d

D’après la documentation officielle de ncu, cette option réduit le risque d’adopter immédiatement une version récemment publiée. Elle ne constitue toutefois pas une analyse de sécurité : conservez vos audits, votre revue des changements et vos tests.

Comment utiliser npm-check-updates dans une CI ?

Pour faire échouer une étape lorsque des mises à jour sont détectées, utilisez le niveau d’erreur prévu pour l’intégration continue :

npx npm-check-updates --errorLevel 2

La commande reste en lecture seule tant que vous n’ajoutez pas -u. Une CI peut donc signaler les écarts sans réécrire package.json.

Dans un monorepo, ncu sait également parcourir les workspaces :

npx npm-check-updates --workspaces --errorLevel 2

Je recommande d’utiliser ce contrôle comme information ou comme règle planifiée, plutôt que de bloquer chaque contribution dès la publication d’une nouvelle version. Une dépendance disponible n’est pas toujours une dépendance à adopter immédiatement.

Quel workflow adopter au quotidien ?

La stratégie la plus fiable consiste à séparer clairement les étapes :

1. Lancez ncu pour examiner les écarts.
2. Appliquez d’abord les correctifs et versions mineures.
3. Installez les dépendances et exécutez les tests.
4. Traitez ensuite chaque version majeure isolément.
5. Validez ensemble package.json et le lockfile.

npm-check-updates n’est pas un bouton de mise à niveau sans risque. C’est un outil de décision qui rend les changements visibles et contrôlables. Pour un projet maintenu activement, je le préfère à l’édition manuelle de package.json, tout en gardant npm outdated pour les diagnostics rapides.

Sources

• npm-check-updates — documentation officielle
• npm outdated — documentation npm
• npm update — documentation npm
• Semantic Versioning 2.0.0