Saltar a contenido

ADR-0003 · La imagen de producción se construye con npm, aunque el repo use Yarn 3

  • Estado: reemplazado por ADR-0005 en cuanto a la estructura de la imagen, y por ADR-0004 en cuanto al gestor de paquetes
  • Decisores: no registrado en el repositorio
  • Fecha de la decisión: no registrada. El Dockerfile vigente aparece en el commit d6fc1a9 ("dockerfile optimized"); el puerto se ajusta en 21111cc ("cambio de puerto de produccion").

Contexto y problema

El repositorio viene del starter de Medusa, que declara "packageManager": "yarn@3.2.3" y versiona yarn.lock. Al contenerizar, la build con Yarn 3 (Plug'n'Play, .yarnrc.yml, releases de Yarn versionadas) resultó más frágil dentro de la imagen que la build con npm. Además hacía falta que la imagen final tuviera exactamente las mismas dependencias que se usaron al compilar, sin reinstalar.

Opciones consideradas

  1. npm install dentro del Dockerfile y copiar node_modules completo del builder al runner (elegida).
  2. Yarn 3 en la imagen, replicando .yarnrc.yml y el release de Yarn.
  3. next build --output standalone, que emite solo las dependencias necesarias.

Decisión

El Dockerfile usa npm install sobre package.json + package-lock.json, corre npm run build y en la etapa de runtime copia el node_modules entero desde el builder en lugar de reinstalar. El comentario del propio archivo lo justifica: "garantiza que tenemos exactamente las mismas dependencias que se usaron en el build". El contenedor arranca con npm start en el puerto 8000; en local se sigue usando yarn dev en el 8001.

Por eso el repositorio versiona los dos lockfiles: yarn.lock para el desarrollo local y package-lock.json para la imagen.

Consecuencias

Positivas

  • Build reproducible dentro de la imagen, sin depender de la instalación de Yarn 3 ni de PnP.
  • El runtime tiene exactamente el árbol de dependencias con el que se compiló.
  • Menos piezas móviles en el Dockerfile.

Negativas / deuda asumida

  • Dos lockfiles que pueden divergir. Una dependencia agregada con yarn add no llega a la imagen hasta que se actualiza package-lock.json: lo que se prueba en local no es necesariamente lo que se despliega. Resuelto por el ADR-0004 (2026-08-26): npm es el gestor único y package-lock.json el único lockfile.
  • npm install (no npm ci) puede resolver versiones distintas entre builds aunque el lockfile no cambie.
  • Copiar node_modules completo incluye las dependencias de desarrollo: la imagen final es bastante más grande que con output: standalone.
  • Todo build de producción reinstala desde cero, lo que alarga el rollback (ver runbook).