npm v12: cambios que pueden romperte

Si trabajas con Node.js, hay una frase que no quieres leer un lunes por la mañana: “breaking changes”. Y cuando el aviso viene de npm, el impacto no se queda en un solo equipo. Puede tocarte el pipeline de CI, la instalación local en desarrollo, la publicación de paquetes privados y hasta scripts que llevas años copiando de un repo a otro.

Eso es justo lo que importa de npm v12: no es solo una actualización de versión, sino una serie de cambios que pueden romper flujos que hoy te parecen estables. Si mantienes aplicaciones, librerías o monorepos, conviene revisar qué cambia, a quién afecta y qué puedes hacer desde ya para no descubrirlo cuando el build ya está fallando.

Qué cambia en npm v12 y por qué te debería importar

La documentación oficial de GitHub sobre los cambios próximos de npm v12 apunta a ajustes que afectan comportamiento, compatibilidad y validaciones alrededor del uso de npm. No estamos hablando únicamente de una nueva interfaz o de pequeños ajustes visuales. El problema real es que algunas decisiones de npm han sido muy permisivas durante años, y ahora se están endureciendo.

Eso suele sonar bien hasta que recuerdas cuántos equipos dependen de comportamientos heredados. Un ejemplo típico: un pipeline que funciona porque npm install tolera una configuración vieja, o una publicación que pasa porque tu registry acepta un flujo que ya no será el predeterminado. Cuando una herramienta cambia el contrato, lo que estaba “medio soportado” deja de serlo.

La referencia oficial está en el changelog de GitHub, y vale la pena leerla en paralelo con la documentación de npm para revisar el comportamiento esperado de cada comando. Puedes empezar por la nota oficial y luego contrastar con la guía de npm sobre instalación y publicación: GitHub Changelog sobre npm v12 y la documentación de npm en docs.npmjs.com.

El tipo de cambio que más duele: el que no rompe en local, pero sí en CI

El peor escenario no es que tu laptop falle. El peor escenario es que tu flujo falle solo en producción o en el runner de CI, porque ahí el entorno es más limpio, más estricto y menos tolerante a “arreglos manuales”. Eso pasa mucho con npm cuando un cambio afecta resolución de dependencias, autenticación o publicación.

Si tu equipo mezcla versiones de Node, usa caches agresivos o depende de archivos de lock generados hace meses, el riesgo sube. No necesitas un caso extremo para sufrirlo: basta con que un job use una versión de npm distinta a la del desarrollador que creó el lockfile. En esos casos, el problema parece aleatorio, pero casi siempre es reproducible si comparas versiones y flags.

Qué se puede romper en la práctica

En la práctica, los impactos se agrupan en tres frentes: instalación, pipelines y publicación. Son los tres lugares donde npm toca el flujo de trabajo diario y donde cualquier cambio de comportamiento se siente de inmediato.

Primero, la instalación. Si npm v12 endurece reglas sobre resolución, peer dependencies, lockfiles o configuración heredada, puedes ver errores al correr npm ci o npm install. Segundo, el pipeline. Un job que antes pasaba con advertencias puede pasar a fallar por una validación nueva. Tercero, la publicación. Si tu proceso usa tokens, scopes o configuraciones de registry muy específicas, una validación más estricta puede bloquear el npm publish.

Aquí conviene pensar en síntomas, no solo en causas. Estas son señales que deberían ponerte en alerta:

• Builds que fallan solo en CI, no en local.
• npm ci que ya no resuelve igual que antes.
• Publicaciones que se quedan en autenticación o en validación de metadata.
• Paquetes privados que dependen de .npmrc heredados o variables de entorno poco claras.
• Monorepos donde cada workspace usa una versión distinta de npm.

Instalaciones: cuando el lockfile deja de ser suficiente

El lockfile no es una garantía mágica. Si cambian las reglas de resolución o la interpretación de ciertas opciones, el mismo package-lock.json puede comportarse distinto entre versiones de npm. En equipos grandes esto se nota rápido, porque una persona actualiza paquetes y otra sigue trabajando con una versión anterior del CLI.

Además, hay un detalle operativo que muchos ignoran: npm ci está pensado para instalaciones reproducibles, pero solo lo es si el entorno también es reproducible. Eso incluye versión de Node, versión de npm, variables de entorno y configuración de registry. Si una de esas piezas cambia, el build deja de ser determinista.

Pipelines: el riesgo de los jobs que asumen defaults viejos

Muchos pipelines están escritos como si npm nunca fuera a cambiar. Un ejemplo clásico es un job que hace npm install, luego npm test y finalmente npm publish, todo sin fijar versión de Node ni de npm. Mientras todo se mantiene igual, parece suficiente. Cuando llega un cambio de comportamiento, ese mismo pipeline se vuelve frágil.

También hay riesgo en los cache layers. Si guardas node_modules o el cache de npm sin controlar bien la versión de la herramienta, puedes estar reinyectando un estado viejo en un job nuevo. Eso genera fallas difíciles de rastrear porque el error no aparece en la misma línea todos los días.

A quién afecta más

No todos los equipos van a sentir el mismo golpe. Si solo consumes paquetes y tu proyecto es pequeño, probablemente el impacto sea menor, aunque no cero. Si mantienes librerías publicadas, monorepos o infraestructura de CI compartida, el riesgo sube bastante.

Los equipos más expuestos suelen ser estos:

1. Equipos de frontend con monorepos y múltiples workspaces.
2. Equipos de plataforma que administran runners de CI/CD.
3. Mantenedores de paquetes privados o públicos publicados con npm.
4. Equipos en empresas medianas que mezclan laptops, contenedores y agentes compartidos.
5. Consultoras o squads distribuidos en Latinoamérica, donde no siempre todos actualizan el stack al mismo ritmo.

En LATAM esto pega más de lo que parece porque es común que un mismo proyecto combine laptops con configuraciones distintas, runners autoalojados y repositorios que no tienen una política estricta de versiones. Si además hay sedes en distintos países, como Ecuador, Colombia, Perú o México, el desorden de versiones crece rápido.

Monorepos y workspaces: donde más se nota la inconsistencia

En un monorepo, un cambio en npm puede tocar varios paquetes a la vez. Si un workspace depende de otro, cualquier diferencia en el comportamiento de instalación o resolución se multiplica. Lo que en un repo simple sería un fallo aislado, en un monorepo termina siendo un problema de coordinación.

Aquí el punto no es solo técnico. También es de proceso. Si un equipo actualiza npm y otro no, terminas con PRs que no se pueden validar de manera consistente. Eso alarga revisiones, crea falsas alarmas y hace perder tiempo en debugging que se pudo evitar con una política de versiones.

Paquetes públicos y privados: publicación y autenticación

Publicar paquetes suele ser el lugar donde más duele un breaking change, porque no hay mucho margen para improvisar. Si el proceso depende de tokens, de un .npmrc heredado o de un registry privado con reglas propias, cualquier ajuste de validación puede bloquear el release.

En equipos que publican paquetes internos para varias apps, esto puede cortar el despliegue de productos completos. No es exageración: un paquete base que no se publica a tiempo puede dejar a varios equipos esperando una dependencia nueva para avanzar.

Cómo prepararte sin frenar al equipo

No necesitas congelar todo el stack. Lo que necesitas es una secuencia corta de validación para detectar dónde te va a pegar npm v12 antes de que llegue a producción. La idea es reducir incertidumbre, no hacer un proyecto paralelo de migración.

Empieza por inventariar tres cosas: versión de Node, versión de npm y forma de instalación/publicación. Si no sabes exactamente qué versión usa cada pipeline, ya tienes el primer problema. Después, compara ese inventario con la versión que quieres probar. El objetivo es encontrar diferencias antes de que te las marque un job fallido.

Te propongo este orden de trabajo:

1. Congela la versión de Node y npm en tus pipelines.
2. Reproduce npm ci y npm publish en un entorno limpio.
3. Revisa .npmrc, tokens y registry configurados por ambiente.
4. Ejecuta una rama de prueba con la nueva versión en un solo repositorio.
5. Documenta el cambio y avisa al resto del equipo con ejemplos concretos.

Qué revisar antes de tocar producción

Antes de actualizar nada, revisa estos puntos con lupa:

• package-lock.json generado con la misma familia de npm que usas en CI.
• Scripts que llaman a npm install sin flags claros.
• Uso de caches compartidos entre ramas o entre proyectos.
• Publicación con tokens almacenados en secretos del runner.
• Configuraciones de registry por entorno en .npmrc.

Si encuentras diferencias entre desarrollo y CI, corrígelas primero. Actualizar npm sobre una base inconsistente solo mueve el problema de lugar.

Prueba controlada: un repo, una rama, una versión

La forma más barata de detectar impacto es hacer una prueba controlada. No necesitas migrar toda la organización de una sola vez. Elige un repositorio representativo, crea una rama de prueba y corre el flujo completo con la nueva versión.

Si quieres hacerlo de forma simple, este patrón ayuda:

node -v
npm -v
npm ci
npm test
npm run build
npm publish --dry-run

Ese --dry-run no te publica nada, pero sí te deja ver si el paquete está listo para salir. Si el problema aparece ahí, mejor descubrirlo en una rama que en un release real.

Estrategia de migración para equipos en LatAm

En Latinoamérica, el problema rara vez es la falta de capacidad técnica. El problema suele ser la mezcla de contextos: horarios distintos, infraestructura heterogénea y prioridades que cambian rápido. Por eso, la migración a npm v12 tiene que ser práctica y con poco ruido.

Lo más útil es trabajar con una política de versiones explícita. Si tu equipo usa Node 20 en producción, no dejes que cada persona use lo que quiera en su máquina. Define una versión, documenta el comando para instalarla y úsala en todos los entornos.

También ayuda separar la validación en dos capas: una capa técnica, donde pruebas npm v12 en un repo piloto, y una capa operativa, donde actualizas plantillas de CI, documentación interna y secretos. Si haces ambas al mismo tiempo, reduces el riesgo de que un equipo quede a medias.

Para equipos en Ecuador o en cualquier otro país de la región, este enfoque es útil porque evita depender de una gran ventana de mantenimiento. Puedes validar en una rama, ajustar scripts y luego desplegar el cambio por etapas. Eso baja el costo de coordinación y evita parar todo por una sola actualización.

Tabla resumen

Si tu equipo depende de npm para instalar, probar y publicar, la actualización no se puede tratar como una tarea menor. El costo de no revisar ahora suele ser más alto después, cuando varios repos empiezan a fallar al mismo tiempo.

La buena noticia es que no necesitas adivinar. Tienes un changelog oficial, puedes reproducir el flujo en un entorno limpio y puedes fijar versiones para cortar la variabilidad. Si haces eso antes de adoptar npm v12, el cambio deja de ser una sorpresa y se vuelve una tarea controlada.