«ERESOLVE unable to resolve dependency tree» de npm y los conflictos de peer dependencies

Qué es

npm error code ERESOLVE (npm 10.6 y posteriores; npm ERR! code ERESOLVE en npm 7 a 10.5) lo genera el propio resolvedor de dependencias de npm. La documentación de npm sobre el formato de package.json describe peerDependencies y el campo overrides, que sirve para ajustarlas. Desde npm 7, las peer dependencies se instalan automáticamente en lugar de limitarse a mostrar una advertencia, de modo que npm ahora debe encontrar una única versión de cada paquete que satisfaga a la vez todos los rangos de peers del árbol. ERESOLVE significa que no lo logró: tu proyecto o una de sus dependencias directas declara un rango de peerDependencies sobre un paquete, y otra dependencia del árbol necesita una versión fuera de ese rango. Los conflictos situados en zonas profundas del árbol se resuelven por defecto solo con la advertencia ERESOLVE overriding peer dependency; --strict-peer-deps hace que también se traten como errores.

Por qué importa

El error no es por sí mismo un informe de que un paquete esté roto; es npm indicando un conflicto real de restricciones que ya existía antes de npm 7, solo que de forma silenciosa. Sortearlo sin entender qué dos requisitos chocan realmente conlleva el riesgo de instalar un árbol que no cumple lo que uno de los paquetes espera en tiempo de ejecución, aunque la instalación en sí termine con éxito.

Cómo aplicarlo

• Diagnóstico: lee el bloque de error completo, no solo la primera línea. npm imprime Found: x@version (lo que está resuelto en ese momento) seguido de una o más líneas Could not resolve dependency: peer x@"range" from y@version que indican exactamente qué paquete necesita qué rango y desde dónde. Después, npm ls <package> --all muestra todos los puntos del árbol que dependen de él.
• Soluciones, de la menos a la más invasiva:
  1. Actualizar los paquetes en conflicto a versiones cuyos rangos de peers sí se solapen. A menudo es la solución real, ya que el conflicto suele reflejar que una dependencia se ha quedado realmente por detrás de las demás.
  2. Si el rango de peers de un paquete es más estricto de lo necesario (declara un rango estrecho, pero se sabe que funciona con la versión mayor más reciente que se usa), fija solo esa resolución anidada con el campo overrides de package.json (npm 8.3+), documentado junto a peerDependencies, en lugar de relajar la comprobación en todo el árbol.
  3. Vía de escape insegura: npm install --legacy-peer-deps, documentada como opción de npm install, restaura el comportamiento de npm 6, que no instala automáticamente los peers ni los comprueba de forma estricta. Funciona, pero impide que npm verifique las expectativas de peers en cualquier parte del árbol, no solo en el conflicto concreto que tienes entre manos.
  4. npm install --force va más allá: instala incluso pasando por encima de otros conflictos que npm detecta. Úsalo como último recurso puntual, no como algo que se deje en CI por defecto, ya que el árbol resultante puede no cumplir lo que un paquete espera al ejecutarse.
• Lo que no es una solución: borrar node_modules y package-lock.json y reinstalar. Si los rangos declarados entran en conflicto, npm falla igual, y se pierden las versiones fijadas en el lockfile.

Trampas

• Recurrir a --force antes de leer qué dos paquetes entran realmente en conflicto, lo que obliga a diagnosticarlo de todos modos cuando algo falla en tiempo de ejecución.
• Dejar --legacy-peer-deps como opción permanente en CI, lo que permite que a partir de entonces se acumulen en silencio nuevos conflictos de peers sin relación con el original.