Solución: npm ERR! code ERESOLVE — conflicto de dependencias en npm

¿Por qué ocurre?

Dos paquetes del proyecto requieren versiones incompatibles de una misma dependencia. Ocurre mucho al actualizar React, Next.js o cualquier librería grande, ya que sus peer dependencies cambian de versión y otros paquetes todavía no se han adaptado.

Solución paso a paso

Opción 1 — --legacy-peer-deps (rápida, funciona el 90% de las veces):

npm install --legacy-peer-deps

Esto ignora los conflictos de peer deps y usa el comportamiento de npm v6. No modifica tu código ni tu package.json.

Opción 2 — --force (más agresiva, úsala solo si la anterior falla):

npm install --force

Opción 3 — leer el error y actualizar el paquete conflictivo:

El error de npm siempre indica qué paquete genera el conflicto:

npm ERR! While resolving: mi-proyecto@1.0.0
npm ERR! Found: react@18.3.0
npm ERR! node_modules/react
npm ERR!   react@"^18.3.0" from the root project
npm ERR!
npm ERR! Could not resolve dependency:
npm ERR! peer react@"^17.0.0" from some-library@2.1.0

En este caso some-library necesita React 17 pero tienes React 18. Soluciones:

# Actualiza el paquete conflictivo a su última versión npm install some-library@latest

# O bájalo a la versión compatible npm install some-library@1.x

Opción 4 — borrar caché y node_modules:

rm -rf node_modules package-lock.json
npm cache clean --force
npm install --legacy-peer-deps

Cómo evitarlo en el futuro

Antes de actualizar una dependencia grande (React, Next.js, Vite…) revisa el changelog para ver si cambió el rango de peer deps. Usa `npm outdated` para ver qué paquetes están desactualizados y actualízalos de forma incremental, no todos a la vez.