Saltar a contenido

ADR-0004 · npm como gestor único y política de actualización de dependencias

  • Estado: aceptado
  • Decisores: equipo TI Compulandia (hquintero)
  • Fecha de la decisión: 2026-08-26

Contexto y problema

Una auditoría de dependencias (2026-08-26) encontró 28 vulnerabilidades conocidas — incluida una crítica de RCE en Next.js — y varios problemas de higiene que impedían actualizar con confianza:

  • Convivían dos lockfiles (yarn.lock v1 y package-lock.json v3) que podían divergir: lo probado en local no era necesariamente lo desplegado (deuda ya señalada en el ADR-0003).
  • package.json declaraba yarn@3.2.3 como gestor, pero Yarn 3 ni siquiera podía leer el yarn.lock v1; en la práctica se instalaba con npm.
  • Los paquetes @medusajs/* estaban en "latest": cada instalación limpia podía traer una versión distinta, sin decisión de nadie y sin relación con la versión de Medusa del backend.
  • No había monitoreo: ni Dependabot/Renovate, ni auditoría de seguridad en CI, ni alertas del repositorio.

Opciones consideradas

  1. npm como gestor único, versiones de Medusa fijadas al backend, Dependabot + auditoría en CI (elegida).
  2. Migrar a Yarn 4 (o pnpm) como gestor único.
  3. Mantener el statu quo (dos lockfiles) y solo parchear vulnerabilidades.

Decisión

npm es el único gestor de paquetes del repositorio. Es el que el equipo ya usaba en la práctica y el que usa la imagen Docker (ADR-0003); Yarn solo sobrevivía como herencia del starter de Medusa. Se eliminaron yarn.lock, .yarnrc.yml y el bloque resolutions (exclusivo de Yarn, npm lo ignoraba); packageManager pasa a npm, y engines exige Node >= 22.

@medusajs/js-sdk y @medusajs/types se fijan sin ^ a la misma versión que @medusajs/medusa en el backend (hoy 2.15.5). Son la superficie del API: adelantarlos o atrasarlos respecto del backend produce errores sutiles. Los paquetes de UI (@medusajs/ui, @medusajs/ui-preset) no están acoplados al API y siguen el ciclo normal de minors.

El monitoreo queda automatizado: Dependabot abre PRs semanales contra develop (patch/minor agrupados; majors individuales; ignora React — fijado por overrides — y los paquetes Medusa acoplados al backend), y un workflow de CI (auditoria-dependencias.yml) corre npm audit en cada PR que toque dependencias y todos los lunes. Los majors (React estable, Next 16, Stripe, Tailwind 4) se migran en etapas planificadas, un PR por major, verificadas en dev-shop antes de producción.

Consecuencias

Positivas

  • Un solo lockfile: lo que se prueba en local es lo que construye la imagen. Desaparece la principal deuda del ADR-0003.
  • Instalaciones reproducibles: nada queda en "latest".
  • Las vulnerabilidades nuevas se detectan por CI y Dependabot, no por auditorías manuales esporádicas.
  • La auditoría inicial bajó de 28 vulnerabilidades a 3 (todas en el postcss embebido de Next 15, sin fix hasta Next 16).

Negativas / deuda asumida

  • Actualizar Medusa ahora es una decisión explícita de dos repositorios: backend primero, storefront después. Nadie lo hará "sin querer" — pero tampoco automáticamente.
  • El gate de CI queda en --audit-level=critical hasta migrar a Next 16; vulnerabilidades high nuevas no bloquean PRs mientras tanto (quedan visibles en Dependabot alerts).
  • Los PRs semanales de Dependabot requieren que alguien los revise y pruebe; sin ese hábito se acumulan y la política muere.
  • React sigue fijado a un RC de React 19 (nov 2024) vía overrides: la migración a React 19 estable es prerequisito de Next 16 y queda como etapa pendiente.