Mejores Prácticas para Gestores de Paquetes

Q: ¿Debemos confirmar node_modules?

No. Confirma solo los lockfiles. CI y Docker reconstruyen node_modules a partir del lockfile.

Q: ¿Qué va en el package.json raíz de un monorepo?

workspaces, herramientas de desarrollo compartidas, scripts de orquestación (build, test, lint). Los desplegables mantienen sus propias dependencias de tiempo de ejecución.

Q: ¿Las bibliotecas deben fijar versiones exactas de las dependencias?

Las bibliotecas usan rangos en package.json; el lockfile de la aplicación fija versiones exactas para el gráfico desplegable.

Q: ¿Cómo incorporamos a nuevos desarrolladores?

Documenta la versión de Node (Volta/nvm), npm ci y npm run dev. engine-strict detecta las discrepancias inmediatamente.

Q: ¿Cómo versionamos los paquetes internos del workspace?

0.0.0 está bien para paquetes solo privados. Aumenta semver antes de publicar externamente o cuando aparezcan consumidores fuera del repositorio.

Reglas que mantienen las instalaciones reproducibles, las auditorías significativas y los monorepos mantenibles.

Cómo Usar Esta Lista

Aplícala en repositorios nuevos antes del primer despliegue a producción.
Revísala al añadir workspaces o cambiar entre npm/pnpm/Yarn.
Hazla cumplir a través de CI (npm ci, puertas de auditoría) en lugar de recordatorios en el README.
Verifica los elementos durante las PRs de actualización de dependencias y los cambios de versión de Node en la plataforma.

A - Política de Gestor y Lockfile

Un gestor de paquetes por repositorio. Los lockfiles mezclados garantizan gráficos node_modules divergentes.
Confirma el lockfile para cada aplicación y servicio desplegable. Las compilaciones reproducibles de CI y Docker dependen de ello.
Usa npm ci en CI, no npm install. Evita la deriva silenciosa de la resolución en cada ejecución del pipeline.
Documenta el gestor elegido en el README. Incluye comandos de instalación, arranque y solución de problemas.
Fija la versión de Node en CI y Docker para que coincida con engines. Por ejemplo, 24.18.0, no solo 24.x flotante.

B - Dependencias y Scripts

Separa dependencies y devDependencies correctamente. TypeScript, ESLint y los ejecutores de pruebas son solo para desarrollo.
Mantén scripts como el contrato de automatización. npm test, npm run build y npm run typecheck funcionan localmente y en CI.
Evita scripts postinstall pesados. Las instalaciones lentas perjudican a cada desarrollador y a cada trabajo de CI en caché.
Usa prepublishOnly para las puertas de publicación. Las pruebas y la verificación de tipos se ejecutan antes de que los tarballs lleguen al registro.
Prefiere CLIs fijadas por lockfile sobre npx desnudo en los scripts. tsx y eslint pertenecen a devDependencies.

C - Workspaces y Monorepos

Usa workspace:* para paquetes internos. Enlaza bibliotecas locales en lugar de rutas file: manuales.
Compila los paquetes compartidos antes que los dependientes. Ordena las tareas en los scripts raíz o usa dependsOn de Turborepo.
Exporta a través de exports del paquete, no importaciones relativas profundas. ../../packages/foo/src entre paquetes rompe los límites.
Un lockfile raíz para todo el monorepo. Los lockfiles por paquete anulan los beneficios de la vinculación de workspaces.
Nombra los workspaces con un alcance consistente. @acme/api, @acme/shared aclara la propiedad.

D - Seguridad y Cumplimiento

Ejecuta npm audit --audit-level=high en cada PR de dependencia. Bloquea la fusión hasta que se corrija o se exceptúe con una fecha de caducidad.
Revisa los cambios en los scripts de instalación en los diffs de dependencias. Las adiciones postinstall son de alto riesgo.
Habilita la procedencia para las bibliotecas internas publicadas. Los consumidores verifican los artefactos construidos por CI.
Establece engine-strict=true en .npmrc. Node no compatible falla en la instalación, no en producción.
Automatiza las actualizaciones de dependencias con PRs agrupadas de Renovate/Dependabot. Lotes de actualización más pequeños y probables.

E - Publicación y Versionado

Usa una lista blanca estricta de files al publicar. Nunca envíes pruebas, secretos .env.example o src/ sin intención.
Sigue semver para los paquetes publicados. Los cambios de API que rompen la compatibilidad requieren aumentos de versión mayores.
Envía JS compilado y .d.ts para bibliotecas TypeScript. Los consumidores no deberían compilar tu código fuente.
Etiqueta las versiones en git al publicar. npm version más la publicación en CI mantiene el registro y el código fuente alineados.
Depreca las versiones incorrectas en lugar de despublicarlas. npm deprecate advierte a los consumidores sin romper los lockfiles.

Preguntas Frecuentes

¿Por qué es tan importante una política de un solo lockfile?

Dos lockfiles significan dos gráficos. CI puede instalar con npm mientras un desarrollador usa Yarn, enmascarando errores hasta la producción.

¿Cuándo es pnpm mejor que npm para backends?

Los monorepos grandes con muchas dependencias transitivas duplicadas se benefician de la eficiencia de disco de pnpm y de sus límites de dependencia más estrictos.

¿Debemos confirmar node_modules?

No. Confirma solo los lockfiles. CI y Docker reconstruyen node_modules a partir del lockfile.

¿Cómo manejamos los parches de emergencia?

Abre una PR actualizando el lockfile, ejecuta CI completo, despliega. Evita npm install directamente en los servidores de producción.

¿Qué va en el package.json raíz de un monorepo?

workspaces, herramientas de desarrollo compartidas, scripts de orquestación (build, test, lint). Los desplegables mantienen sus propias dependencias de tiempo de ejecución.

¿Las bibliotecas deben fijar versiones exactas de las dependencias?

Las bibliotecas usan rangos en package.json; el lockfile de la aplicación fija versiones exactas para el gráfico desplegable.

¿Cómo incorporamos a nuevos desarrolladores?

Documenta la versión de Node (Volta/nvm), npm ci y npm run dev. engine-strict detecta las discrepancias inmediatamente.

¿Es suficiente npm audit para la cadena de suministro?

Necesario pero no suficiente. Añade Socket o similar para el análisis de comportamiento y la detección de typosquatting.

¿Cuándo debemos cambiar de gestor de paquetes?

Cuando el tiempo de instalación del monorepo o los errores de dependencia fantasma perjudican la velocidad. Planifica una migración en una sola PR con regeneración del lockfile y CI completo.

¿Cómo versionamos los paquetes internos del workspace?

0.0.0 está bien para paquetes solo privados. Aumenta semver antes de publicar externamente o cuando aparezcan consumidores fuera del repositorio.

Relacionado

Conceptos Básicos de Gestores de Paquetes - selección de npm, pnpm, Yarn
Lockfiles e Instalaciones Reproducibles - detalles de npm ci
Cadena de Suministro: npm audit y Socket - puertas de fusión

Versiones de la pila: Esta página fue escrita para Node.js 24.18.0 (LTS Activo), npm 10+, TypeScript 5.6+, Express 5, Fastify 5 y NestJS 11.

Mejores Prácticas para Gestores de Paquetes

Reglas que mantienen las instalaciones reproducibles, las auditorías significativas y los monorepos mantenibles.

Cómo Usar Esta Lista

Aplícala en repositorios nuevos antes del primer despliegue a producción.
Revísala al añadir workspaces o cambiar entre npm/pnpm/Yarn.
Hazla cumplir a través de CI (npm ci, puertas de auditoría) en lugar de recordatorios en el README.
Verifica los elementos durante las PRs de actualización de dependencias y los cambios de versión de Node en la plataforma.

A - Política de Gestor y Lockfile

Un gestor de paquetes por repositorio. Los lockfiles mezclados garantizan gráficos node_modules divergentes.
Confirma el lockfile para cada aplicación y servicio desplegable. Las compilaciones reproducibles de CI y Docker dependen de ello.
Usa npm ci en CI, no npm install. Evita la deriva silenciosa de la resolución en cada ejecución del pipeline.
Documenta el gestor elegido en el README. Incluye comandos de instalación, arranque y solución de problemas.
Fija la versión de Node en CI y Docker para que coincida con engines. Por ejemplo, 24.18.0, no solo 24.x flotante.

B - Dependencias y Scripts

Separa dependencies y devDependencies correctamente. TypeScript, ESLint y los ejecutores de pruebas son solo para desarrollo.
Mantén scripts como el contrato de automatización. npm test, npm run build y npm run typecheck funcionan localmente y en CI.
Evita scripts postinstall pesados. Las instalaciones lentas perjudican a cada desarrollador y a cada trabajo de CI en caché.
Usa prepublishOnly para las puertas de publicación. Las pruebas y la verificación de tipos se ejecutan antes de que los tarballs lleguen al registro.
Prefiere CLIs fijadas por lockfile sobre npx desnudo en los scripts. tsx y eslint pertenecen a devDependencies.

C - Workspaces y Monorepos

Usa workspace:* para paquetes internos. Enlaza bibliotecas locales en lugar de rutas file: manuales.
Compila los paquetes compartidos antes que los dependientes. Ordena las tareas en los scripts raíz o usa dependsOn de Turborepo.
Exporta a través de exports del paquete, no importaciones relativas profundas. ../../packages/foo/src entre paquetes rompe los límites.
Un lockfile raíz para todo el monorepo. Los lockfiles por paquete anulan los beneficios de la vinculación de workspaces.
Nombra los workspaces con un alcance consistente. @acme/api, @acme/shared aclara la propiedad.

D - Seguridad y Cumplimiento

Ejecuta npm audit --audit-level=high en cada PR de dependencia. Bloquea la fusión hasta que se corrija o se exceptúe con una fecha de caducidad.
Revisa los cambios en los scripts de instalación en los diffs de dependencias. Las adiciones postinstall son de alto riesgo.
Habilita la procedencia para las bibliotecas internas publicadas. Los consumidores verifican los artefactos construidos por CI.
Establece engine-strict=true en .npmrc. Node no compatible falla en la instalación, no en producción.
Automatiza las actualizaciones de dependencias con PRs agrupadas de Renovate/Dependabot. Lotes de actualización más pequeños y probables.

E - Publicación y Versionado

Usa una lista blanca estricta de files al publicar. Nunca envíes pruebas, secretos .env.example o src/ sin intención.
Sigue semver para los paquetes publicados. Los cambios de API que rompen la compatibilidad requieren aumentos de versión mayores.
Envía JS compilado y .d.ts para bibliotecas TypeScript. Los consumidores no deberían compilar tu código fuente.
Etiqueta las versiones en git al publicar. npm version más la publicación en CI mantiene el registro y el código fuente alineados.
Depreca las versiones incorrectas en lugar de despublicarlas. npm deprecate advierte a los consumidores sin romper los lockfiles.

Preguntas Frecuentes

¿Por qué es tan importante una política de un solo lockfile?

Dos lockfiles significan dos gráficos. CI puede instalar con npm mientras un desarrollador usa Yarn, enmascarando errores hasta la producción.

¿Cuándo es pnpm mejor que npm para backends?

Los monorepos grandes con muchas dependencias transitivas duplicadas se benefician de la eficiencia de disco de pnpm y de sus límites de dependencia más estrictos.

¿Debemos confirmar node_modules?

No. Confirma solo los lockfiles. CI y Docker reconstruyen node_modules a partir del lockfile.

¿Cómo manejamos los parches de emergencia?

Abre una PR actualizando el lockfile, ejecuta CI completo, despliega. Evita npm install directamente en los servidores de producción.

¿Qué va en el package.json raíz de un monorepo?

workspaces, herramientas de desarrollo compartidas, scripts de orquestación (build, test, lint). Los desplegables mantienen sus propias dependencias de tiempo de ejecución.

¿Las bibliotecas deben fijar versiones exactas de las dependencias?

Las bibliotecas usan rangos en package.json; el lockfile de la aplicación fija versiones exactas para el gráfico desplegable.

¿Cómo incorporamos a nuevos desarrolladores?

Documenta la versión de Node (Volta/nvm), npm ci y npm run dev. engine-strict detecta las discrepancias inmediatamente.

¿Es suficiente npm audit para la cadena de suministro?

Necesario pero no suficiente. Añade Socket o similar para el análisis de comportamiento y la detección de typosquatting.

¿Cuándo debemos cambiar de gestor de paquetes?

Cuando el tiempo de instalación del monorepo o los errores de dependencia fantasma perjudican la velocidad. Planifica una migración en una sola PR con regeneración del lockfile y CI completo.

¿Cómo versionamos los paquetes internos del workspace?

0.0.0 está bien para paquetes solo privados. Aumenta semver antes de publicar externamente o cuando aparezcan consumidores fuera del repositorio.

Relacionado

Conceptos Básicos de Gestores de Paquetes - selección de npm, pnpm, Yarn
Lockfiles e Instalaciones Reproducibles - detalles de npm ci
Cadena de Suministro: npm audit y Socket - puertas de fusión

Versiones de la pila: Esta página fue escrita para Node.js 24.18.0 (LTS Activo), npm 10+, TypeScript 5.6+, Express 5, Fastify 5 y NestJS 11.

Mejores Prácticas para Gestores de Paquetes

Buscar en la documentación

Mejores Prácticas para Gestores de Paquetes