npm ERR Peer Dependency : Résoudre les Conflits npm

Tu lances npm install et tu reçois un mur de texte rouge : npm ERR! ERESOLVE unable to resolve dependency tree. Ton projet ne s'installe plus. Voici ce que ça veut dire et les 3 solutions pour s'en sortir.

C'est quoi une peer dependency ?

Une peer dependency est une dépendance qu'un package exige que TU aies installée dans ton projet, au lieu de l'installer lui-même.

Analogie : imagine un plugin Photoshop. Le plugin (package) ne contient pas Photoshop — il dit "j'ai besoin que Photoshop version 2024+ soit installé sur ta machine". C'est une peer dependency.

// package.json de react-dom
{
  "peerDependencies": {
    "react": "^18.0.0 || ^19.0.0"
  }
}
// → react-dom dit : "j'ai besoin que react 18 ou 19 soit dans TON projet"

Les 3 types de dépendances npm :

Pourquoi npm bloque (depuis npm 7+)

Avant npm 7, les conflits de peer dependencies étaient des warnings ignorés silencieusement. Depuis npm 7 (Node 15+), npm est strict : s'il détecte un conflit, il refuse d'installer.

Voici comment lire le message d'erreur :

npm ERR! ERESOLVE unable to resolve dependency tree
npm ERR!
npm ERR! While resolving: mon-projet@1.0.0
npm ERR! Found: react@19.0.0              # ← Tu as React 19
npm ERR! node_modules/react
npm ERR!
npm ERR! Could not resolve dependency:
npm ERR! peer react@"^18.0.0" from react-old-lib@2.1.0  # ← Ce package veut React 18
npm ERR! node_modules/react-old-lib

Traduction : react-old-lib demande React 18, mais tu as React 19. npm ne sait pas lequel choisir.

Les 3 solutions (de la meilleure à la dernière option)

Solution 1 : Mettre à jour les packages (recommandé)

La meilleure approche : mettre à jour le package qui cause le conflit pour qu'il supporte ta version.

# Voir quels packages sont obsolètes
npm outdated

# Mettre à jour un package spécifique
npm install react-old-lib@latest

# Mettre à jour tout
npm update

Quand l'utiliser : toujours essayer en premier. Dans 60% des cas, une version plus récente du package résout le conflit.

Solution 2 : --legacy-peer-deps

Revenir au comportement d'npm 6 : ignorer les conflits de peer dependencies.

# Ignorer les peer dependencies pour cette installation
npm install --legacy-peer-deps

# Rendre permanent pour ce projet
echo "legacy-peer-deps=true" >> .npmrc

Quand l'utiliser : quand le package fonctionne réellement avec ta version malgré le conflit déclaré (souvent le cas avec React). Risque : faible — tu reviens au comportement pré-npm 7.

Solution 3 : --force (dernier recours)

Forcer l'installation en ignorant TOUS les conflits.

# Forcer l'installation
npm install --force

Quand l'utiliser : quand rien d'autre ne marche et que tu es prêt à tester manuellement que tout fonctionne. Risque : moyen — tu peux te retrouver avec des versions incompatibles qui crashent au runtime.

Comment éviter ce problème

1. Vérifier la compatibilité avant d'installer : lis le README du package, vérifie les peerDependencies sur npm
2. Utiliser npm ls pour voir l'arbre de dépendances :

# Voir l'arbre complet
npm ls

# Voir uniquement un package
npm ls react

# Voir les problèmes
npm ls --all 2>&1 | grep "WARN"

3. Ne jamais supprimer package-lock.json "pour résoudre" — ça crée plus de problèmes que ça n'en résout. Le lockfile garantit des installations reproductibles.
4. Garder les dépendances à jour : npm outdated régulièrement pour éviter les gros écarts de version.

Résumé

FAQ

C'est quoi la différence entre --legacy-peer-deps et --force ?
--legacy-peer-deps ignore uniquement les conflits de peer dependencies (comportement npm 6). --force ignore TOUS les conflits et peut écraser des packages existants. Préfère toujours --legacy-peer-deps.

Est-ce que je peux supprimer package-lock.json pour résoudre ?
Non. Le lockfile garantit que tout le monde installe les mêmes versions. Le supprimer peut créer de nouveaux conflits. Si tu veux repartir de zéro : supprime node_modules/ (pas le lockfile) et relance npm install.

Pourquoi ça marchait avant et plus maintenant ?
Probablement parce que tu as mis à jour Node.js (donc npm). npm 7+ (Node 15+) est strict sur les peer dependencies. Avant, les conflits étaient des warnings silencieux.

Est-ce que yarn ou pnpm ont le même problème ?
Yarn (v1) est plus permissif et installe les peer deps automatiquement. pnpm est strict comme npm 7+. Si tu veux éviter ces problèmes, yarn est souvent plus simple pour les débutants.

Pour bien démarrer un projet : guide React 2026 et les commandes Git essentielles.

Envie de pratiquer ? GoGoKodo propose des ateliers interactifs pour apprendre JavaScript en codant directement dans le navigateur — 100% gratuit.