npm « ERESOLVE unable to resolve dependency tree » et conflits de dépendances peer

Ce que c'est

npm error code ERESOLVE (npm 10.6 et versions ultérieures ; npm ERR! code ERESOLVE de npm 7 à 10.5) provient du résolveur de dépendances de npm lui-même. La documentation de npm sur le format de package.json décrit peerDependencies ainsi que le champ overrides qui permet de les ajuster. Depuis npm 7, les dépendances peer sont installées automatiquement au lieu de simplement donner lieu à un avertissement ; npm doit donc désormais trouver, pour chaque paquet, une version unique qui satisfait en même temps toutes les plages peer de l'arbre. ERESOLVE signifie qu'il n'y est pas parvenu : votre projet, ou l'une de ses dépendances directes, déclare une plage peerDependencies sur un paquet, et une autre dépendance de l'arbre requiert une version située en dehors de cette plage. Par défaut, les conflits situés en profondeur dans l'arbre sont résolus avec un simple avertissement ERESOLVE overriding peer dependency ; --strict-peer-deps les transforme eux aussi en échecs.

Pourquoi c'est important

Cette erreur n'est pas, en soi, le signalement d'un paquet défectueux : c'est npm qui signale un véritable conflit de contraintes, qui existait déjà avant npm 7, mais de façon silencieuse. Contourner l'erreur sans comprendre quelles sont les deux exigences qui entrent réellement en collision risque de produire un arbre qui ne satisfait pas ce que l'un des paquets attend à l'exécution, bien que l'installation elle-même réussisse.

Comment l'appliquer

• Diagnostic : lisez le bloc d'erreur complet, pas seulement sa première ligne. npm affiche Found: x@version (ce qui est actuellement résolu), suivi d'une ou plusieurs lignes Could not resolve dependency: peer x@"range" from y@version qui indiquent précisément quel paquet exige quelle plage, et depuis où. La commande npm ls <package> --all montre ensuite tous les endroits de l'arbre qui en dépendent.
• Corrections, de la moins invasive à la plus invasive :
  1. Mettre à jour le ou les paquets en conflit vers des versions dont les plages peer se recoupent réellement. C'est souvent la vraie solution, car le conflit reflète fréquemment le fait qu'une dépendance est réellement en retard sur les autres.
  2. Si la plage peer d'un paquet est simplement plus stricte que la réalité (il déclare une plage étroite, mais il est connu pour fonctionner avec la version majeure plus récente utilisée), fixer uniquement cette résolution imbriquée avec le champ overrides de package.json (npm 8.3+), documenté avec peerDependencies, plutôt que d'assouplir la vérification pour tout l'arbre.
  3. Échappatoire risquée : npm install --legacy-peer-deps, documentée comme option de npm install, rétablit le comportement de npm 6, qui n'installe pas automatiquement les dépendances peer et ne les vérifie pas strictement. Cela fonctionne, mais npm cesse alors de vérifier les attentes peer partout dans l'arbre, et pas seulement pour le conflit en cause.
  4. npm install --force va plus loin : il installe même en présence d'autres conflits détectés par npm. Il faut le considérer comme un dernier recours ponctuel, et ne pas l'inscrire par défaut dans la CI, car l'arbre obtenu peut ne pas satisfaire ce qu'un paquet attend lorsqu'il s'exécute.
• Ce n'est pas une correction : supprimer node_modules et package-lock.json puis réinstaller. Si les plages déclarées sont en conflit, npm échoue de la même manière, et les versions épinglées du lockfile sont perdues.

Pièges

• Recourir à --force avant d'avoir lu quels sont les deux paquets réellement en conflit ; il faudra de toute façon faire ce diagnostic dès que quelque chose cassera à l'exécution.
• Valider --legacy-peer-deps comme option permanente de la CI, ce qui laisse ensuite s'accumuler silencieusement de nouveaux conflits peer sans rapport avec le premier.