Mejores prácticas para bibliotecas esenciales

Reglas que mantienen las dependencias de npm mantenibles, seguras y consistentes en los servicios Node.js.

Cómo usar esta lista

• Aplícala al iniciar un nuevo servicio de API o worker.
• Revísala durante los sprints trimestrales de higiene de dependencias.
• Hazla cumplir mediante puertas de auditoría de CI y casillas de verificación de plantillas de PR.
• Marca los elementos al incorporar una biblioteca o al retirar una antigua.

A - Selección y estándares

• Documenta la pila esencial predeterminada en CONTRIBUTING.md. zod, pino, got o axios, Luxon, BullMQ + ioredis a menos que el ADR diga lo contrario.
• Evalúa los nuevos paquetes con una lista de verificación escrita. Mantenimiento, respuesta de seguridad, licencia, peso transitivo.
• Requiere un enlace ADR para bibliotecas no predeterminadas. Mínimo un párrafo en docs/adr/.
• Prefiere primero los módulos integrados de Node 24. fetch, node:test, node:crypto antes que sus equivalentes de npm.
• Una biblioteca por preocupación por servicio. Sin superposición de moment + Luxon + date-fns.
• Rechaza paquetes con hallazgos de auditoría altos no mitigados. Ticket de excepción con fecha de caducidad.

B - Fijación y actualizaciones

• Confirma el lockfile en cada cambio de dependencia. package-lock.json o equivalente de pnpm/yarn.
• Usa npm ci en CI, nunca npm install. Gráficos reproducibles en cada ejecución de pipeline.
• Fija Node en los motores a LTS Activo. 24.18.0 alineado con .nvmrc y la imagen base de Docker.
• Agrupa los PR de Renovate/Dependabot semanalmente. Menor radio de explosión que las mega-actualizaciones mensuales.
• Ejecuta typecheck y el conjunto completo de pruebas en PRs solo de lockfile. Las rupturas transitivas ocurren sin ediciones directas de dependencias.
• Alinea las versiones de los paquetes del espacio de trabajo compartido. Las dependencias peer de @acme/shared-* coinciden con las dependencias del servicio.

C - Seguridad y cadena de suministro

• Ejecuta npm audit --audit-level=high en cada PR. Bloquea la fusión hasta que se corrija o se exceptúe.
• Revisa los scripts de instalación en las diferencias del lockfile. Las adiciones de postinstall son de alto riesgo.
• Habilita la procedencia para los paquetes internos publicados. Los consumidores verifican los artefactos construidos por CI.
• Escanea con Socket o similar para riesgo proactivo. Más allá de la auditoría solo de CVE.
• No se deben confirmar secretos en dependencias o .env. Usa la inyección de plataforma y los administradores de secretos.
• Minimiza el recuento de complementos nativos. Cada complemento es una superficie de compilación y cadena de suministro.

D - Operaciones por biblioteca

• Zod solo en los límites. HTTP, entorno, cargas útiles de cola, no todas las funciones internas.
• Pino JSON a stdout en producción. No pino-pretty en imágenes de producción; redacta los encabezados de autenticación.
• Clientes HTTP: tiempos de espera y reintentos en todas las llamadas salientes. Reintento idempotente solo a menos que existan claves de idempotencia.
• Luxon o UTC explícito para la programación. No new Date("cadena local") sin desplazamiento.
• Workers de BullMQ como procesos separados. No dentro del bucle de eventos del servidor HTTP.
• Los prefijos de clave de Redis separan la caché de las claves de la cola. cache: vs prefijo interno de BullMQ.

E - Desuso e higiene

• Desuso con ventana de migración y prohibición de lint en nuevas importaciones. Realiza un seguimiento por repositorio en un problema de GitHub.
• Elimina las dependencias no utilizadas con depcheck trimestralmente. Los paquetes muertos siguen fallando la auditoría.
• Documenta las actualizaciones importantes en CHANGELOG. Especialmente las actualizaciones importantes de Zod, Fastify, BullMQ.
• Reevalúa los ADR anualmente. La rotación de mantenedores o mejores módulos integrados pueden dejar obsoletas las opciones.
• Capacita a los revisores sobre las señales de alerta de los PR de dependencias. Bibliotecas duplicadas, lockfile faltante, omisión de auditoría.

Preguntas frecuentes

Relacionado

• Conceptos básicos de bibliotecas esenciales - introducción a la selección, fijación y desuso
• zod - validación en los límites
• pino - registro de producción
• got / axios - políticas HTTP salientes
• date-fns / Luxon - zonas horarias
• bullmq / ioredis - cola + caché
• Mejores prácticas de administradores de paquetes - política de lockfile

Versiones de 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.