Deuda con el upstream y con las dependencias

Notas de un análisis comparativo entre este repositorio y el starter oficial del que nació, hecho el 2026-08-19. No hay acción pendiente inmediata; este documento existe para ejecutarlo cuando corresponda y para no repetir el análisis.

Resumen en una línea

El starter del que venimos está deprecado y más atrasado que nosotros. No hay nada que traer de ahí. Lo que sí hace falta es un upgrade de dependencias propio, sobre todo salir de React 19 RC.

De dónde venimos, exactamente

El repositorio arranca con un commit squasheado (aeb9cc2, 2025-09-23) sin historia previa. Comparando árboles de archivos, el punto de fork es inequívoco:

Upstream	medusajs/nextjs-starter-medusa
Commit base	1277359 — fix: handle when no region with country configured (#520), 2025-09-19
Verificación	src/ idéntico byte a byte entre aeb9cc2 y 1277359
Divergencia desde entonces	154 archivos, +12.562 / −1.324 líneas en src/

El upstream está deprecado

9818886  2026-04-23  chore: add deprecation note (#568)
+ > ⚠️ This repository is now deprecated. Use the dtc-starter instead.

Desde nuestra base el upstream publicó 21 commits en 7 meses y después cerró el repositorio. El reemplazo oficial es medusajs/dtc-starter: un monorepo (backend + storefront, pnpm + turbo), arquitectura distinta a la nuestra. Está activo — Next 15.5.21, Medusa v2.19.0.

Migrar a dtc-starter sería reescribir, no actualizar. Con 12.5k líneas propias encima del starter, no se recomienda.

Qué publicó el upstream y por qué no lo traemos

De los 23 archivos que tocó el upstream desde nuestra base, 13 chocan con archivos que nosotros modificamos.

Cambio upstream	Veredicto
Selector de idioma / i18n (7 commits, dic-2025): locale-actions.ts, locales.ts, header x-medusa-locale inyectado en config.ts	No aplica. Tienda monolingüe, región única py. Choca con config.ts, nav, cart.ts.
Medusa Payments (73d9d81): proveedor pp_medusa-payments_default, renombra isStripe → isStripeLike	No aplica. Cobramos con pp_bancard_qr y pp_bank_transfer. Choca con 4 archivos de checkout.
Imágenes por variante (2d10a09): retrieveVariant() + search param ?variant=	Ya resuelto, y mejor. Nuestra ruta products/[handle]/[[...variantId]]/ cubre el caso con URL propia. Adoptarlo rompería el enrutamiento.
Backdrop en el side-menu (c70162e): click-fuera para cerrar, z-index 30 → 51	Mejora menor. Si se quiere, se copia a mano en minutos.
Rename get-precentage-diff → get-percentage-diff (c7499a0)	Solo corrige el typo en el nombre del archivo. Cosmético. Seguimos con el nombre viejo.
Variables S3 + next.config.js (66f8fee)	Solo si algún día servimos imágenes desde Medusa Cloud.
@medusajs/icons faltante (ff1c768)	Verificar si nos falta el paquete declarado.

Conclusión: ninguna funcionalidad del upstream vale la pena traer.

Lo que sí hay que hacer: dependencias

Esto es independiente del upstream. Ojo: el upstream está más atrasado que nosotros en Next, así que no es la referencia.

Paquete	Instalado hoy	Upstream (deprecado)	Último en npm
next	15.5.4	15.3.9 ⬅ más viejo	15.5.23 (o 16.3.1)
react / react-dom	19.0.0-rc (nov-2024)	19.0.5 estable	19.2.8
@medusajs/js-sdk	2.10.3	latest	2.19.0
@medusajs/ui	4.0.23	latest	4.2.1
@stripe/stripe-js	1.54.2	^8.2.0	—
@stripe/react-stripe-js	1.16.5	^5.3.0	—

npm audit --omit=dev reporta 21 vulnerabilidades (1 crítica, 9 altas). La crítica es next, con avisos que incluyen RCE vía React flight protocol (GHSA-9qr9-h5gf-34mp), bypass de middleware/proxy y cache poisoning. También aparecen lodash, fast-uri y la cadena react-instantsearch → ai → @ai-sdk/provider-utils.

Plan sugerido, en orden

1. React 19 RC → 19.2.8 estable. Somos el único que sigue en una RC de noviembre de 2024. Al hacerlo se borran el bloque overrides y el resolutions con el alias npm:types-react@19.0.0-rc.1 del package.json — ese hack deja de ser necesario.
2. Next 15.5.4 → 15.5.23. Mismo minor, sin breaking changes esperados, trae los parches de seguridad. Verificar con npm audit después del bump: no dar por sentado que limpia todos los avisos.
3. @medusajs/* 2.10.3 → 2.19.0, alineado con la versión del backend.
4. Decidir sobre Stripe. Están dos majors atrás y el código está inactivo (cobramos por Bancard QR y transferencia). O se actualizan, o se saca la dependencia del package.json y se limpia el código muerto de checkout.

Hacerlo en una rama aparte y con el checkout probado punta a punta — es la zona con más código propio.

Cómo reproducir este análisis

git clone https://github.com/medusajs/nextjs-starter-medusa.git upstream-storefront
cd upstream-storefront
git remote add fork /ruta/al/storefront && git fetch fork 'refs/heads/*:refs/remotes/fork/*'

# Confirmar el punto de fork (debe dar 0 archivos)
git diff --name-only 1277359 <commit-inicial-del-fork> -- src/ | wc -l

# Qué publicó el upstream desde entonces
git log --no-merges --format='%ad %h %s' --date=short 1277359..main
git diff --stat 1277359 main -- src/

# Qué archivos chocan con los nuestros
comm -12 <(git diff --name-only 1277359 main -- src/ | sort) \
         <(git diff --name-only 1277359 fork/<rama> -- src/ | sort)