Saltar a contenido

ADR-0003 · Instalar con npm y legacy-peer-deps, no con pnpm

  • Estado: aceptado
  • Decisores: no registrado en el repositorio (autoría del código: hquintero1)
  • Fecha de la decisión: 2025-12-03, fecha del commit fea2e5f ("fixes de compilacion y construccion de imagen docker") que la implementa.

Contexto y problema

El template de Payload asume pnpm: todos los scripts de package.json invocan pnpm, engines declara "pnpm": "^9 || ^10" y el Dockerfile original detectaba el lockfile presente para elegir entre yarn, npm (npm ci) o pnpm.

Al dockerizar el proyecto, el build se rompía en la etapa de instalación de dependencias. npm ci exige que package-lock.json esté perfectamente sincronizado con package.json, y el árbol de dependencias —Payload 3.61 con React 19 y un conjunto de plugins de Radix y Payload— tenía conflictos de peer dependencies que abortaban la instalación.

Opciones consideradas

  1. npm con legacy-peer-deps=true y npm install en vez de npm ci (elegida)
  2. Adoptar pnpm de verdad: generar pnpm-lock.yaml, instalarlo en la imagen y alinear los scripts
  3. Resolver los conflictos de peer dependencies uno por uno y mantener npm ci estricto

Decisión

npm, con legacy-peer-deps=true fijado en .npmrc y npm install --legacy-peer-deps en el Dockerfile (el commit reemplazó el bloque multi-gestor por esa única línea, y bajó la restricción de react-hook-form de 7.45.4 a ^7.54.0). Solo se commitea package-lock.json; no existe pnpm-lock.yaml.

Fue la opción que desbloqueaba el build sin auditar el árbol completo de dependencias de Payload, que es upstream y no está bajo nuestro control.

Consecuencias

Positivas

  • El docker build es reproducible y no depende de instalar pnpm en la imagen.
  • No hace falta corregir peer dependencies de paquetes upstream para poder desplegar.

Negativas / deuda asumida

  • El repo miente sobre sí mismo. Los scripts de package.json siguen diciendo pnpm, y engines sigue exigiéndolo: npm test, npm run test:e2e y npm run dev:prod fallan si pnpm no está instalado. Hay que invocar vitest y playwright directamente (ver AGENTS.md). El webServer.command de Playwright tiene el mismo problema.
  • legacy-peer-deps silencia conflictos reales de versiones: una incompatibilidad se va a manifestar en runtime en vez de fallar en la instalación.
  • npm install en el Dockerfile puede resolver versiones distintas a las del lockfile, así que el build no es bit-a-bit determinista.