Conceptos básicos de las bibliotecas esenciales

10 ejemplos de cómo seleccionamos, fijamos y retiramos las dependencias de npm en backends de Node.js 24 TypeScript, 7 básicos y 3 intermedios.

Prerrequisitos

• Node.js 24.18.0 (LTS activa) y npm 10+.
• Un gestor de paquetes por repositorio con un lockfile confirmado; consulta Conceptos básicos de los gestores de paquetes.
• Plantilla ADR del equipo para añadir o eliminar dependencias en tiempo de ejecución.

Ejemplos básicos

1. Pila esencial predeterminada

Inicia nuevos servicios con este conjunto seleccionado antes de evaluar alternativas.

• Documenta la pila predeterminada en CONTRIBUTING.md para que las PR no vuelvan a debatir los conceptos básicos semanalmente.
• Las desviaciones requieren un comentario ADR de un párrafo en la PR.
• Consulta las páginas dedicadas: zod, pino, got / axios.

Relacionado: Mejores prácticas de las bibliotecas esenciales - lista de verificación de selección

2. Lista de verificación de evaluación antes de añadir una dependencia

Puntúa a los candidatos antes de npm install.

## Evaluación de dependencia: <package-name>
- [ ] Última publicación < 12 meses O mantenedor LTS explícito
- [ ] Problemas abiertos respondidos en ~2 semanas para informes de seguridad
- [ ] Descargas semanales estables o en crecimiento (no un pico abandonado)
- [ ] Tipos de TypeScript integrados o calidad verificada por DefinitelyTyped
- [ ] No hay scripts de instalación a menos que se revisen (riesgo de cadena de suministro)
- [ ] Recuento transitivo aceptable (npm ls <pkg> --all)
- [ ] Licencia compatible (MIT/Apache-2.0 típico)

• Rechaza los paquetes con avisos de seguridad sin mantenimiento y sin ruta de bifurcación.
• Ejecuta npm audit después de la instalación; bloquea la alta gravedad sin un ticket de excepción.
• Prefiere los paquetes que el equipo ya opera en otro servicio; la familiaridad operativa cuenta.

3. Fija las versiones principales, confía en el lockfile

package.json expresa la intención; el lockfile expresa la realidad.

{
  "dependencies": {
    "zod": "^3.24.0",
    "pino": "^9.0.0",
    "ioredis": "^5.4.0"
  },
  "engines": {
    "node": "24.18.0"
  }
}

npm install          # actualiza el lockfile localmente con la intención
npm ci               # CI instala el lockfile exacto - nunca se desvía

• Usa el circunflejo en las bibliotecas que actualizas a través de PR agrupadas de Renovate.
• Fija versiones exactas solo para paquetes problemáticos conocidos (temporalmente).
• Nunca confirmes sin actualizar el lockfile cuando cambien las dependencias.

Relacionado: Lockfiles e instalaciones reproducibles

4. Prefiere los módulos integrados antes que npm

Node 24 reduce la superficie de terceros para tareas comunes.

// fetch integrado - no se requiere got/axios para GET simples
const res = await fetch("https://api.example.com/health");
const body = await res.json();
 
// Ejecutor de pruebas integrado - no se requiere jest para servicios pequeños
import { test } from "node:test";
import assert from "node:assert/strict";
 
test("health shape", () => {
  assert.equal(typeof body.status, "string");
});

• Añade got o axios cuando necesites políticas de reintento, agentes o interceptores a escala.
• Añade jest o vitest cuando necesites ecosistemas de mocking más allá de node:test.
• Menos dependencias significa menos fallos de auditoría y un npm ci más rápido.

Relacionado: Conceptos básicos de las API integradas

5. Una biblioteca por preocupación

Las bibliotecas de fechas o clientes HTTP duplicados crean un comportamiento inconsistente e imágenes infladas.

# Audita la superposición antes de aprobar una PR
npm ls moment date-fns luxon dayjs 2>/dev/null
npm ls axios got undici node-fetch 2>/dev/null

• Aplica en la revisión de código: "¿Esta PR introduce una segunda biblioteca para el mismo trabajo?"
• Los paquetes internos compartidos envuelven la biblioteca elegida para que los servicios no importen tres pilas HTTP.

6. Documenta el porqué en los comentarios de package.json (enlace ADR)

Vincula las dependencias inusuales a un registro de decisiones.

{
  "dependencies": {
    "bullmq": "^5.0.0",
    "ioredis": "^5.4.0"
  }
}

<!-- docs/adr/003-job-queue.md -->
# ADR 003: BullMQ para trabajos asíncronos
- Estado: aceptado
- Contexto: Necesidad de trabajos retrasados, reintentos, DLQ con Redis ya en la pila
- Decisión: BullMQ sobre listas de Redis sin procesar
- Consecuencias: Operar Redis HA; monitorear la profundidad de la cola

• Los ADR viven en docs/adr/ y están vinculados desde las descripciones de las PR.
• Revisa los ADR cuando el paquete tenga un incidente de seguridad importante o un cambio de mantenedor.

7. Puertas de seguridad y cadena de suministro

Trata las nuevas dependencias como un riesgo de producción, no como una conveniencia.

npm audit --audit-level=high
npx socket npm audit   # opcional: escaneo proactivo de la cadena de suministro

# .github/workflows/pr-checks.yml (extracto)
- run: npm ci
- run: npm audit --audit-level=high

• Bloquea la fusión en avisos de alta/crítica gravedad no mitigados en dependencias directas o transitivas.
• Revisa los scripts postinstall en las diferencias del lockfile; se ejecutan en cada portátil de desarrollador.
• Habilita la procedencia para los paquetes internos publicados.

Relacionado: Cadena de suministro: npm audit & Socket

Ejemplos intermedios

8. Retirar una biblioteca (ventana de deprecación)

Elimina las dependencias con un plan de migración, no con una eliminación masiva.

## Plan de retiro: winston → pino
Semana 1: ADR aceptado; no hay nuevas importaciones de winston (regla de lint)
Semana 2-3: Migrar servicios de alto tráfico; registro dual si es necesario
Semana 4: Eliminar winston de package.json; npm audit confirma que se ha ido

// Adaptador transitorio - eliminar después de la migración
import pino from "pino";
export const log = pino({ level: process.env.LOG_LEVEL ?? "info" });

• Anuncia en #backend con la lista de servicios afectados.
• Rastrea el progreso en un problema de GitHub con casillas de verificación por repositorio.
• Elimina de la lista de permitidos de Renovate de toda la organización cuando esté completo.

9. Alineación de versiones en servicios de monorepo

Las bibliotecas compartidas fuerzan versiones transitivas consistentes.

{
  "name": "@acme/shared-validation",
  "dependencies": {
    "zod": "^3.24.0"
  },
  "peerDependencies": {
    "zod": "^3.24.0"
  }
}

• Los paquetes del espacio de trabajo exportan esquemas Zod; los servicios importan @acme/shared-validation.
• Un grupo de Renovate actualiza zod en todos los archivos package.json semanalmente.
• Ejecuta npm run typecheck en la raíz del repositorio después de las actualizaciones agrupadas.

Relacionado: Workspaces y Monorepos

10. Cuándo decir no a una dependencia

Rechaza los paquetes que no cumplen con los estándares del equipo, incluso si son populares en npm.

• "No inventado aquí" es incorrecto; "no operado aquí" es válido.
• Los prototipos individuales pueden experimentar; los servicios de producción siguen la pila esencial.

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