Comprender y resolver conflictos de dependencias ERESOLVE de npm

Comprendiendo y resolviendo conflictos de dependencias npm ERESOLVE

Un error npm ERESOLVE significa que npm no pudo construir un árbol de dependencias que satisfaga todas las reglas de versión, generalmente debido a las peer dependencies. Desde npm 7, las peer dependencies se manejan estrictamente durante la instalación, por lo que los conflictos que antes se instalaban "de todos modos" ahora fallan rápidamente.

Esa rigurosidad reduce las sorpresas en tiempo de ejecución, pero puede bloquear las instalaciones cuando un paquete espera versiones más antiguas que las de tu proyecto.

Triaje rápido: Encuentra el conflicto real

Antes de forzar nada, identifica quién requiere qué. Estos comandos suelen localizar al culpable en menos de un minuto.

npm -v
node -v

# mostrar cadena de dependencias
npm ls @tensorflow/tfjs
npm ls react

# mostrar requisitos de peer dependencies
npm view @tensorflow-models/handpose peerDependencies

# explicar por qué se eligió una versión
npm explain @tensorflow/tfjs

¿Por qué ocurren los conflictos de peer dependencies?

Las peer dependencies son contratos de compatibilidad. Una librería dice: "Yo no incluyo React / TFJS por mi cuenta; tú debes proporcionar una versión compatible". Los conflictos ocurren cuando dos paquetes exigen rangos de versiones incompatibles.

• El paquete A requiere @tensorflow/tfjs ^3, pero tu proyecto instala @tensorflow/tfjs@4.
• Un plugin requiere react@^17, mientras que tu aplicación está en react@18.
• Mezclaste versiones mayores en una familia de paquetes (por ejemplo, tfjs core v4, backends todavía en v3).

Cómo solucionar npm ERESOLVE (De lo más seguro a lo más agresivo)

1) Alinear versiones (La mejor solución a largo plazo)

Mantén una versión mayor compatible en toda la familia de dependencias. Esta es la solución que sobrevive a la CI, los despliegues y las futuras actualizaciones.

// package.json (ejemplo: alinear la familia tfjs en v3)
{
  "dependencies": {
    "@tensorflow/tfjs": "^3.21.0",
    "@tensorflow/tfjs-backend-webgl": "^3.21.0",
    "@tensorflow/tfjs-backend-cpu": "^3.21.0",
    "@tensorflow-models/handpose": "^0.0.7"
  }
}

rm -rf node_modules package-lock.json
npm install

2) Usar "overrides" de npm (Forzado controlado, npm 8+)

Usa overrides cuando una dependencia transitiva atraiga la versión incorrecta. Esto es más seguro que --force, pero debes probar el comportamiento en tiempo de ejecución.

// package.json
{
  "overrides": {
    "@tensorflow/tfjs": "^4.0.0",
    "@tensorflow/tfjs-backend-webgl": "^4.0.0",
    "@tensorflow/tfjs-backend-cpu": "^4.0.0"
  }
}

rm -rf node_modules package-lock.json
npm install

3) --legacy-peer-deps (Desbloqueo rápido, menos seguridad)

Omite la resolución estricta de pares e instala de todos modos. Bueno para experimentos rápidos; arriesgado como predeterminado en producción.

npm install --legacy-peer-deps

4) --force (Último recurso)

Fuerza una instalación incluso cuando npm sabe que el árbol es inconsistente. Úselo solo si acepta posibles fallos en tiempo de ejecución.

npm install --force

5) Lista de verificación para una instalación limpia (corrige estados extraños del lockfile)

rm -rf node_modules package-lock.json
npm cache verify
npm install

npm vs pnpm vs Yarn: Diferencias prácticas

Los tres pueden tener conflictos de pares, pero difieren en velocidad, estrategia de node_modules y qué tan rápido exponen errores de dependencia "ocultos".

npm (v7+): estricto por defecto

• Pros: detecta combinaciones de pares incompatibles de forma temprana; CI predecible.
• Contras: bloquea las instalaciones con más frecuencia; la gente recurre a los flags.
• Ideal para: equipos que prefieren la corrección estricta sobre la conveniencia.

pnpm: rápido, eficiente en disco, acceso a dependencias más estricto

pnpm utiliza un almacén global direccionable por contenido y enlaza paquetes. Las instalaciones suelen ser más rápidas y utilizan menos disco. Su diseño más estricto puede revelar antes la falta de dependencias directas.

corepack enable
corepack prepare pnpm@latest --activate

pnpm install

Yarn: herramientas sólidas para workspaces, resoluciones flexibles

Yarn es popular en monorepos. Dependiendo de la versión/configuración de Yarn puede parecer más permisivo, pero la gran ventaja son los workspaces y su capacidad para fijar versiones mediante resolutions.

corepack enable
corepack prepare yarn@stable --activate

yarn install

# package.json (Yarn) -> "resolutions": { "react": "18.2.0" }

Conclusión

Para producción: prefiera alinear versiones o overrides controlados. Use --legacy-peer-deps para desbloquear rápidamente y reserve --force como último recurso. Si las instalaciones son lentas o el repositorio es grande, pnpm suele ser una mejora sólida. Si los espacios de trabajo y el anclaje estricto son importantes, Yarn es una buena opción.

Fragmentos para copiar y pegar

# lo más seguro: alinear versiones
rm -rf node_modules package-lock.json
npm install

# controlado: overrides
# package.json -> "overrides": { "pkg": "version" }

# desbloqueo rápido
npm install --legacy-peer-deps

# último recurso
npm install --force