Reglas de Dependencia
Las reglas de dependencia mantienen los gráficos de instalación pequeños, auditables y mantenidos para que los servicios de producción no hereden paquetes abandonados o vulnerables.
Receta
Tarjeta de receta de referencia rápida - lista para copiar y pegar.
{
"dependencies": {
"fastify": "^5.0.0"
},
"scripts": {
"audit": "npm audit --audit-level=high"
}
}npm ci
npm audit --audit-level=highCuándo usarlo:
- Al añadir cualquier dependencia npm a un servicio o biblioteca compartida.
- Revisión semanal de higiene de la plataforma.
- Respuesta a incidentes después de un aviso de la cadena de suministro.
Ejemplo de Trabajo
# docs/dependencies.md (en el repositorio)
## Añadir una dependencia (RFC-lite)
1. Necesidad declarada en la descripción del PR
2. Descargas semanales > 100k O excepción aprobada por la organización
3. Última publicación < 12 meses atrás
4. Sin scripts de instalación O revisados en el diff del PR
5. Licencia MIT/Apache-2.0/ISC solo para dependencias de producción# .github/workflows/audit.yml
on:
schedule:
- cron: "0 6 * * 1"
pull_request:
paths: [package.json, package-lock.json]
jobs:
audit:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- run: npm ci
- run: npm audit --audit-level=high// Prefiere los módulos nativos de Node cuando sean suficientes
import { createHash, randomUUID } from "node:crypto";
// en lugar de añadir `uuid` + `crypto-js` para necesidades básicasLo que esto demuestra:
- Lista de verificación del PR antes de que lleguen nuevos paquetes.
- Auditoría semanal programada más una puerta de PR en los cambios del lockfile.
node:cryptoincorporado evita dependencias adicionales para UUID/hash.
Análisis Profundo
Cómo Funciona
- Los rangos de
package.jsonpermiten actualizaciones compatibles; el lockfile fija versiones exactas. - Renovate/Dependabot abre PRs de actualización probados según un horario.
npm auditinforma sobre CVEs conocidos en el gráfico bloqueado.- Los paquetes abandonados acumulan CVEs sin parchear y dependencias pares incompatibles.
Política de Fijación de Versiones
| Tipo de dependencia | Política de rango |
|---|---|
| Framework (express, fastify, nest) | Actualizaciones menores cuidadosas, suite de pruebas |
Internas @acme/* | workspace o publicación semver |
| Transitivas | Controladas solo a través del lockfile |
| devDependencies | Fija versiones mayores; actualiza con la cadena de herramientas |
Notas de TypeScript
- Las devDependencies
@types/*siguen a DefinitelyTyped; elimínalas cuando el paquete incluya sus propios tipos (Express 5). - Alinea
@types/nodecon Node 24.
Errores comunes
- Añadir lodash para una función - Impuesto de dependencia de 4MB para siempre. Solución: JS nativo o utilidad de 10 líneas en
packages/utils. - Ignorar la auditoría porque "no hay solución" - Deuda silenciosa durante meses. Solución: ticket de excepción con control compensatorio y fecha de caducidad.
- Dependencia de GitHub en la rama
master- Fuente mutable no fijada. Solución: lanzamiento semver desde npm o SHA de etiqueta git. - Bibliotecas superpuestas duplicadas -
momentydate-fnsydayjs. Solución: una única biblioteca de fechas estándar de la organización. - Paquetes con scripts de instalación sin revisión - Riesgo de la cadena de suministro. Solución: bloqueo en Socket/política de PR.
Alternativas
| Alternativa | Usar Cuándo | No Usar Cuándo |
|---|---|---|
| Vender un pequeño fragmento MIT | Función única, licencia clara | Código grande o GPL |
| Proxy de registro privado | Cachea y escanea todos los tarballs | Proyecto hobby en solitario |
| Política de cero dependencias para libs | Paquetes publicados | Aplicaciones internas con dependencias normales |
Preguntas Frecuentes
¿Fijar versiones exactas en package.json?
Las aplicaciones usan rangos + lockfile. Las bibliotecas usan rangos para los consumidores; evita fijar versiones exactas a menos que sea necesario.
¿Cómo detectar paquetes abandonados?
Verifica la última fecha de publicación, problemas abiertos, descargas de npm; Socket señala las señales de falta de mantenimiento.
¿Podemos usar dependencias GPL?
Generalmente, evítalas en servicios propietarios; se requiere revisión legal para copyleft.
¿Cuántas dependencias directas son demasiadas?
No hay un número fijo; cuestiona cada adición. >50 dependencias directas justifican una revisión periódica de knip y auditoría.
¿Campo overrides en package.json?
Úsalo con moderación para forzar un parche transitivo; documenta la razón en el PR; los overrides confunden a Renovate.
¿Advertencias de dependencias peer?
Soluciona antes de fusionar; los plugins de Nest/ESLint a menudo necesitan instalaciones peer explícitas.
¿Deben los workers compartir el lockfile con la API?
Monorepo: sí, un único lockfile raíz. Polyrepo: auditorías independientes por cada desplegable.
¿Qué tan rápido parchear un CVE crítico?
SLA de 24-48h para RCE alcanzable en la pila HTTP; haz seguimiento en el tablero de incidentes.
¿Se auditan las devDependencies?
Sí, por el riesgo de la máquina del desarrollador; también ejecuta npm ci --omit=dev para auditar el gráfico de producción.
¿Proceso de reemplazo de un paquete obsoleto?
ADR o ticket, rama de migración, elimina la dependencia antigua en el mismo PR que la nueva implementación.
Relacionado
- Lista de Verificación de Reglas del Proyecto Node - regla 10
- Cadena de Suministro: npm audit & Socket - lista de verificación de auditoría
- Reglas de Seguridad - seguridad a nivel de aplicació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.