Noções Básicas de Bibliotecas Essenciais

10 exemplos de como selecionamos, fixamos e desativamos dependências npm em backends Node.js 24 TypeScript - 7 básicos e 3 intermediários.

Pré-requisitos

• Node.js 24.18.0 (Active LTS) e npm 10+.
• Um gerenciador de pacotes por repositório com um lockfile comprometido - veja Noções Básicas de Gerenciadores de Pacotes.
• Modelo ADR da equipe para adicionar ou remover dependências de tempo de execução.

Exemplos Básicos

1. Pilha Essencial Padrão

Comece novos serviços com este conjunto selecionado antes de avaliar alternativas.

• Documente a pilha padrão em CONTRIBUTING.md para que os PRs não debatam os básicos semanalmente.
• Desvios exigem um comentário ADR de um parágrafo no PR.
• Veja páginas dedicadas: zod, pino, got / axios.

Relacionado: Melhores Práticas de Bibliotecas Essenciais - checklist de seleção

2. Checklist de Avaliação Antes de Adicionar uma Dependência

Pontue candidatos antes de npm install.

## Avaliação de dependência: <nome-do-pacote>
- [ ] Última publicação < 12 meses OU mantenedor explícito de LTS
- [ ] Problemas abertos respondidos em ~2 semanas para relatórios de segurança
- [ ] Downloads semanais estáveis ou crescendo (não pico de abandono)
- [ ] Tipos TypeScript integrados ou qualidade DefinitelyTyped verificada
- [ ] Sem scripts de instalação, a menos que revisados (risco de cadeia de suprimentos)
- [ ] Contagem transitiva aceitável (npm ls <pkg> --all)
- [ ] Licença compatível (MIT/Apache-2.0 típico)

• Rejeite pacotes com avisos de segurança não mantidos e sem caminho de fork.
• Execute npm audit após a instalação; bloqueie gravidade alta sem ticket de exceção.
• Prefira pacotes que a equipe já opera em outro serviço - familiaridade operacional conta.

3. Fixe Versões Principais, Confie no Lockfile

package.json expressa a intenção; o lockfile expressa a realidade.

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

npm install          # atualiza o lockfile localmente com a intenção
npm ci               # CI instala o lockfile exato - nunca desvie

• Use o circunflexo em bibliotecas que você atualiza via PRs agrupados do Renovate.
• Fixe versões exatas apenas para pacotes com problemas conhecidos (temporário).
• Nunca comite sem atualizar o lockfile quando as dependências mudarem.

Relacionado: Lockfiles e Instalações Reproduzíveis

4. Prefira Built-ins Antes do npm

Node 24 reduz a superfície de terceiros para tarefas comuns.

// fetch integrado - não precisa de got/axios para GET simples
const res = await fetch("https://api.example.com/health");
const body = await res.json();
 
// Test runner integrado - não precisa de jest para serviços pequenos
import { test } from "node:test";
import assert from "node:assert/strict";
 
test("formato de saúde", () => {
  assert.equal(typeof body.status, "string");
});

• Adicione got ou axios quando precisar de políticas de retentativa, agentes ou interceptadores em escala.
• Adicione jest ou vitest quando precisar de ecossistemas de mock além de node:test.
• Menos dependências significam menos falhas de auditoria e npm ci mais rápido.

Relacionado: Noções Básicas de APIs Integradas

5. Uma Biblioteca por Preocupação

Bibliotecas de data ou clientes HTTP duplicados criam comportamento inconsistente e imagens inchadas.

# Audite sobreposição antes de aprovar um PR
npm ls moment date-fns luxon dayjs 2>/dev/null
npm ls axios got undici node-fetch 2>/dev/null

• Aplique em revisão de código: "Este PR introduz uma segunda biblioteca para o mesmo trabalho?"
• Pacotes internos compartilhados encapsulam a biblioteca escolhida para que os serviços não importem três pilhas HTTP.

6. Documente o Porquê em Comentários do package.json (Link ADR)

Vincule dependências incomuns a um registro de decisão.

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

<!-- docs/adr/003-job-queue.md -->
# ADR 003: BullMQ para jobs assíncronos
- Status: aceito
- Contexto: Necessidade de jobs atrasados, retentativas, DLQ com Redis já na pilha
- Decisão: BullMQ em vez de listas Redis brutas
- Consequências: Operar Redis HA; monitorar profundidade da fila

• ADRs ficam em docs/adr/ e são vinculados a partir das descrições de PR.
• Revise ADRs quando o pacote tiver um incidente de segurança importante ou mudança de mantenedor.

7. Portões de Segurança e Cadeia de Suprimentos

Trate novas dependências como risco de produção, não conveniência.

npm audit --audit-level=high
npx socket npm audit   # opcional: escaneamento proativo da cadeia de suprimentos

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

• Bloqueie a mesclagem em avisos de alta/crítica não mitigados em dependências diretas ou transitivas.
• Revise scripts postinstall em diffs de lockfile - eles rodam em todos os laptops de desenvolvedor.
• Habilite proveniência para pacotes internos publicados.

Relacionado: Cadeia de Suprimentos: npm audit & Socket

Exemplos Intermediários

8. Desativar uma Biblioteca (Janela de Depreciação)

Remova dependências com um plano de migração, não uma exclusão abrupta.

## Plano de desativação: winston → pino
Semana 1: ADR aceito; sem novas importações de winston (regra de lint)
Semana 2-3: Migrar serviços de alto tráfego; log duplo se necessário
Semana 4: Remover winston do package.json; npm audit confirma a remoção

// Adaptador de transição - excluir após a migração
import pino from "pino";
export const log = pino({ level: process.env.LOG_LEVEL ?? "info" });

• Anuncie em #backend com a lista de serviços afetados.
• Acompanhe o progresso em um issue do GitHub com caixas de seleção por repositório.
• Remova da lista de permissões do Renovate de toda a organização quando concluído.

9. Alinhamento de Versão Entre Serviços Monorepo

Bibliotecas compartilhadas forçam versões transitivas consistentes.

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

• Pacotes de workspace exportam esquemas Zod; serviços importam @acme/shared-validation.
• Um grupo Renovate atualiza zod em todos os arquivos package.json semanalmente.
• Execute npm run typecheck na raiz do repositório após atualizações agrupadas.

Relacionado: Workspaces & Monorepos

10. Quando Dizer Não a uma Dependência

Recuse pacotes que falham no padrão da equipe, mesmo que sejam populares no npm.

• "Não inventado aqui" está errado; "não operado aqui" é válido.
• Protótipos solo podem experimentar; serviços de produção seguem a pilha essencial.

Versões da Pilha: Esta página foi escrita para Node.js 24.18.0 (Active LTS), npm 10+, TypeScript 5.6+, Express 5, Fastify 5 e NestJS 11.