El archivo que nadie vigila y que rompe tu CI sin avisar
Hay un error que aparece en casi todos los equipos de desarrollo en algún momento: el entorno local funciona perfectamente, pero el pipeline de integración continua falla. Nadie modificó el package.json. No hubo cambios en la lógica del código. Y sin embargo, el comportamiento es distinto dependiendo de dónde se ejecute el proyecto. Este es el famoso "works on my machine" — y tiene una causa mucho más concreta de lo que parece.
El escenario es sencillo: un desarrollador corre npm install en su máquina local y obtiene la versión 2.5.0 de una dependencia. El servidor de CI corre npm ci y obtiene la versión 2.4.3. Mismo repositorio, mismo package.json, resultados distintos. El culpable es un solo archivo comprometido en el repo — o más exactamente, la ausencia de ese archivo gestionado correctamente.
En este artículo explicamos qué archivo es, por qué importa tanto, y cómo evitar que este problema destruya la confianza en tus despliegues.
npm install vs npm ci: no son lo mismo
La mayoría de desarrolladores usa npm install en el día a día sin pensar demasiado en ello. Este comando resuelve las dependencias según los rangos definidos en package.json — si una librería tiene definida la versión ^2.4.0, npm puede instalar cualquier versión compatible, incluyendo la 2.5.0 si ya existe en el registro.
npm ci, en cambio, es completamente diferente en su filosofía. Este comando ignora el package.json como fuente de verdad y se basa exclusivamente en el package-lock.json. Si ese archivo dice 2.4.3, instala 2.4.3 — sin excepciones, sin actualizaciones automáticas. Si el lockfile no existe o está desincronizado, el comando simplemente falla.
Esta diferencia de comportamiento es exactamente lo que genera la discrepancia entre entornos. Y es por diseño: npm ci fue creado para entornos de integración continua donde la reproducibilidad es crítica.
El archivo que explica todo: package-lock.json
El archivo en cuestión es el package-lock.json. Este archivo registra la versión exacta de cada dependencia instalada — no los rangos, sino los números de versión precisos. Es el contrato entre tu entorno de desarrollo y cualquier otro entorno donde corra el proyecto.
El problema ocurre cuando este archivo no está comprometido en el repositorio, está en el .gitignore por error, o fue modificado localmente sin hacer commit. En ese caso, npm install en la máquina del desarrollador genera un lockfile actualizado con las versiones más recientes disponibles, mientras que el CI trabaja con un lockfile desactualizado — o directamente resuelve las versiones desde cero.
El resultado es predecible: dos versiones distintas de una misma librería corriendo en dos entornos distintos, con comportamientos que pueden diferir de formas sutiles o catastróficas dependiendo de qué cambió entre versiones.
¿Cómo aplica esto en equipos de desarrollo en Perú y LATAM?
Este problema es especialmente frecuente en equipos que están creciendo rápido — startups y empresas medianas que están formalizando sus procesos de desarrollo por primera vez. En muchos proyectos de la región, el enfoque inicial es "si funciona en local, suficiente". Pero cuando el equipo crece, cuando se incorpora un pipeline de CI/CD, o cuando se trabaja con múltiples desarrolladores en paralelo, esta deuda técnica cobra factura.
Los síntomas más comunes que vemos en proyectos son: builds que fallan en producción sin razón aparente, bugs que solo se reproducen en ciertos entornos, y horas perdidas en debugging que termina descubriendo que dos desarrolladores tenían versiones distintas de una dependencia crítica.
La buena noticia es que la solución es simple y no requiere herramientas adicionales — solo disciplina de equipo y una política clara.
¿Cómo aplica esto en tu empresa?
Hay tres acciones concretas que puedes implementar hoy mismo para evitar este problema en tu equipo:
- Commitea siempre el package-lock.json. Este archivo debe vivir en el repositorio junto al código. Si está en tu
.gitignore, sácalo de ahí ahora mismo. - Usa npm ci en todos tus pipelines de CI/CD. No
npm install. El comandonpm cigarantiza que el entorno de integración instala exactamente lo que el lockfile especifica — sin sorpresas. - Establece una política de equipo sobre actualizaciones de dependencias. Las actualizaciones deben ser deliberadas — con un PR dedicado, revisión de cambios y validación en CI — no accidentales por correr
npm installen local.
Si usas Yarn, el equivalente es el yarn.lock. Si usas pnpm, es el pnpm-lock.yaml. El principio es idéntico: el lockfile es la fuente de verdad para la reproducibilidad de entornos.
Conclusión
Un solo archivo mal gestionado puede generar horas de debugging, builds rotos y pérdida de confianza en el proceso de despliegue. El package-lock.json no es un detalle técnico menor — es parte de la infraestructura de confiabilidad de tu proyecto. Tratarlo como tal es una decisión de madurez de equipo.
En Consultoría-Ti acompañamos a equipos de desarrollo en Perú y Latinoamérica a establecer procesos de CI/CD robustos, arquitecturas de software mantenibles y buenas prácticas que reducen la deuda técnica desde el inicio. Si tu equipo está creciendo y quieres asegurarte de que sus procesos escalen bien, conversemos.
Contáctanos en Consultoría-Ti y cuéntanos en qué etapa está tu proyecto.
Fuentes y Referencias
Google for Developers — Package management developer challenge (YouTube Shorts)
✨ Contenido generado con ContentFlow — Consultoría-Ti