ERESOLVE signale des dépendances incompatibles. Exécutez les commandes à la racine d’un projet géré avec npm, sans changer son gestionnaire ni supprimer son lockfile.
Lire les deux côtés du conflit
Dans le message npm, repérez Found, puis Could not resolve dependency et la ligne peer. Exemple fictif :
Found: framework@4.0.0
Could not resolve dependency:
peer framework@"^3.0.0" from plugin@2.0.0Ici, le plugin attend la version majeure 3 du framework, mais le projet utilise la 4. Réinstaller les mêmes versions ne peut pas corriger cette incompatibilité.
Vérifiez aussi l’environnement :
node --version
npm --version
npm pkg get engines packageManager dependencies devDependencies
git status --shortAlignez Node et npm sur les versions prévues par le projet et la CI. Une erreur EBADENGINE concerne cette compatibilité et demande un diagnostic distinct.
Trouver qui impose la version
Dans les commandes suivantes, remplacez NOM_DU_PAQUET, NOM_DU_PLUGIN et VERSION_CANDIDATE par les valeurs de votre erreur :
npm ls NOM_DU_PAQUET
npm explain NOM_DU_PAQUET
npm view NOM_DU_PLUGIN@VERSION_CANDIDATE peerDependencies enginesnpm ls peut sortir avec une erreur lorsqu’il détecte un arbre invalide : sa sortie reste utile. npm explain décrit l’installation présente ; si elle n’existe pas encore, partez du rapport ERESOLVE et des métadonnées renvoyées par npm view.
Une peerDependency est une compatibilité attendue avec un paquet fourni par le projet, par exemple React pour un composant React. Elle ne signifie pas que deux versions majeures seront interchangeables.
Aligner les dépendances
Choisissez selon le projet : mettre le plugin à une version compatible, conserver une version du framework qu’il prend en charge, ou remplacer le plugin s’il n’est plus maintenu. Consultez son guide de migration avant une mise à jour majeure.
Après avoir choisi la version, installez-la dans la même catégorie qu’avant :
npm install NOM_DU_PLUGIN@VERSION_COMPATIBLEPour un outil déjà placé dans devDependencies, utilisez plutôt npm install --save-dev NOM_DU_PLUGIN@VERSION_COMPATIBLE. Dans un monorepo npm, ciblez le workspace concerné avec --workspace NOM_DU_WORKSPACE.
Si plusieurs versions doivent changer ensemble, ajustez leurs contraintes dans package.json, puis lancez npm install une fois. Relisez ensuite :
git diff -- package.json package-lock.json
npm ls NOM_DU_PAQUETNe supprimez pas le lockfile par réflexe : cela peut renouveler de nombreuses dépendances sans rapport avec le conflit. Un overrides doit rester une correction ciblée dont vous avez vérifié la compatibilité.
Comprendre les contournements
| Option | Effet | Limite |
|---|---|---|
--legacy-peer-deps |
Ignore les contrats de peerDependencies pendant la construction de l’arbre | L’installation peut réussir avec des paquets incompatibles |
--force |
Désactive plusieurs protections npm | Peut accepter des conflits et des versions non prises en charge |
npm cache verify |
Contrôle le cache | Ne résout pas des contraintes de versions contradictoires |
Pour un ancien projet qui dépend déjà de legacy-peer-deps, gardez sa configuration cohérente entre le poste et la CI le temps d’organiser la migration. Vérifiez les valeurs actives avec npm config get legacy-peer-deps et npm config get force ; ne changez pas la configuration globale pour corriger un seul dépôt.
Valider avec une installation propre
Après avoir sauvegardé votre travail, lancez :
npm ci
npm runnpm ci remplace node_modules, exige un lockfile cohérent avec package.json et n’actualise pas ces fichiers. Les installations peuvent exécuter les scripts des dépendances : travaillez avec des paquets de confiance.
npm run liste les scripts disponibles. Exécutez les tests, le contrôle de types et le build prévus par le projet. Commitez ensemble le manifeste, le lockfile et toute configuration npm de projet nécessaire. Une installation réussie ne prouve pas à elle seule que le plugin fonctionne.