Regras de Dependência

Regras de dependência mantêm os grafos de instalação pequenos, auditáveis e mantidos para que os serviços de produção não herdem pacotes abandonados ou vulneráveis.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

{
  "dependencies": {
    "fastify": "^5.0.0"
  },
  "scripts": {
    "audit": "npm audit --audit-level=high"
  }
}

npm ci
npm audit --audit-level=high

Quando usar isto:

Ao adicionar qualquer dependência npm a um serviço ou biblioteca compartilhada.
Revisão semanal de higiene da plataforma.
Resposta a incidentes após aviso de cadeia de suprimentos.

Exemplo de Trabalho

# docs/dependencies.md (no repositório)
 
## Adicionar uma dependência (RFC-lite)
1. Necessidade declarada na descrição do PR
2. Downloads semanais > 100k OU exceção aprovada pela organização
3. Última publicação < 12 meses atrás
4. Sem scripts de instalação OU revisado no diff do PR
5. Licença MIT/Apache-2.0/ISC apenas para dependências de produção

# .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

// Prefira built-ins do Node quando suficientes
import { createHash, randomUUID } from "node:crypto";
// em vez de adicionar `uuid` + `crypto-js` para necessidades básicas

O que isto demonstra:

Checklist de PR antes que novos pacotes sejam incluídos.
Auditoria semanal agendada mais um portão de PR em alterações de lockfile.
node:crypto integrado evita dependência extra para UUID/hash.

Mergulho Profundo

Como Funciona

Intervalos package.json permitem atualizações compatíveis; lockfile fixa versões exatas.
Renovate/Dependabot abre PRs de atualização testados conforme agendado.
npm audit relata CVEs conhecidos no grafo travado.
Pacotes abandonados acumulam CVEs não corrigidos e dependências de pares incompatíveis.

Política de Fixação de Versão

Tipo de Dep	Política de Intervalo
Framework (express, fastify, nest)	Atualizações menores cuidadosas, suíte de testes
`@acme/*` Interno	workspace ou semver publish
Transitiva	Controlada apenas via lockfile
devDependencies	Fixe versões principais; atualize com toolchain

Notas de TypeScript

@types/* devDeps rastreiam DefinitelyTyped; remova quando o pacote enviar seus próprios tipos (Express 5).
Alinhe @types/node com Node 24.

Armadilhas

Adicionar lodash para uma única função - Custo de dependência de 4MB para sempre. Correção: JS nativo ou utilitário de 10 linhas em packages/utils.
Ignorar auditoria porque "não há correção" - Dívida silenciosa por meses. Correção: ticket de exceção com controle compensatório e expiração.
Dependência do GitHub no branch master - Fonte mutável não fixada. Correção: release semver do npm ou SHA de tag git.
Bibliotecas duplicadas sobrepostas - moment e date-fns e dayjs. Correção: escolha única da biblioteca de data padrão da organização.
Pacotes com script de instalação sem revisão - Risco de cadeia de suprimentos. Correção: bloqueio na política do Socket/PR.

Alternativas

Alternativa	Use Quando	Não Use Quando
Vender um pequeno trecho MIT	Função única, licença clara	Código grande ou GPL
Proxy de registro privado	Cache e escaneie todos os tarballs	Projeto solo de hobby
Política zero-dep para libs	Pacotes publicados	Aplicativos internos com dependências normais

FAQs

Fixar versões exatas em package.json?

Aplicativos usam intervalos + lockfile. Bibliotecas usam intervalos para consumidores; evite fixações exatas, a menos que necessário.

Como detectar pacotes abandonados?

Verifique a última data de publicação, issues abertas, downloads npm; Socket sinaliza indicadores de não manutenção.

Podemos usar dependências GPL?

Geralmente evite em serviços proprietários; revisão legal necessária para copyleft.

Quantas dependências diretas são muitas?

Sem número fixo; questione cada adição. >50 dependências diretas justificam revisão periódica de knip e auditoria.

Campo overrides em package.json?

Use com moderação para forçar um patch transitivo; documente o motivo no PR; overrides confundem o Renovate.

Avisos de dependência de par?

Corrija antes de mesclar; plugins Nest/ESLint frequentemente precisam de instalações de par explícitas.

Workers devem compartilhar lockfile com a API?

Monorepo: sim, lockfile raiz único. Polyrepo: auditorias independentes por deploy.

Quão rápido corrigir CVE crítico?

SLA de 24-48h para RCE alcançável na pilha HTTP; rastreie no quadro de incidentes.

DevDependencies são auditadas?

Sim, para risco da máquina do desenvolvedor; também execute npm ci --omit=dev audit para o grafo de produção.

Processo de substituição de pacote obsoleto?

ADR ou ticket, branch de migração, remova a dependência antiga no mesmo PR da nova implementação.

Relacionado

Checklist de Regras de Projeto Node - regra 10
Cadeia de Suprimentos: npm audit & Socket - checklist de auditoria
Regras de Segurança - segurança em nível de aplicativo

Versões da Stack: 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.

Regras de Dependência

Regras de dependência mantêm os grafos de instalação pequenos, auditáveis e mantidos para que os serviços de produção não herdem pacotes abandonados ou vulneráveis.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

{
  "dependencies": {
    "fastify": "^5.0.0"
  },
  "scripts": {
    "audit": "npm audit --audit-level=high"
  }
}

npm ci
npm audit --audit-level=high

Quando usar isto:

Ao adicionar qualquer dependência npm a um serviço ou biblioteca compartilhada.
Revisão semanal de higiene da plataforma.
Resposta a incidentes após aviso de cadeia de suprimentos.

Exemplo de Trabalho

# docs/dependencies.md (no repositório)
 
## Adicionar uma dependência (RFC-lite)
1. Necessidade declarada na descrição do PR
2. Downloads semanais > 100k OU exceção aprovada pela organização
3. Última publicação < 12 meses atrás
4. Sem scripts de instalação OU revisado no diff do PR
5. Licença MIT/Apache-2.0/ISC apenas para dependências de produção

# .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

// Prefira built-ins do Node quando suficientes
import { createHash, randomUUID } from "node:crypto";
// em vez de adicionar `uuid` + `crypto-js` para necessidades básicas

O que isto demonstra:

Checklist de PR antes que novos pacotes sejam incluídos.
Auditoria semanal agendada mais um portão de PR em alterações de lockfile.
node:crypto integrado evita dependência extra para UUID/hash.

Mergulho Profundo

Como Funciona

Intervalos package.json permitem atualizações compatíveis; lockfile fixa versões exatas.
Renovate/Dependabot abre PRs de atualização testados conforme agendado.
npm audit relata CVEs conhecidos no grafo travado.
Pacotes abandonados acumulam CVEs não corrigidos e dependências de pares incompatíveis.

Política de Fixação de Versão

Tipo de Dep	Política de Intervalo
Framework (express, fastify, nest)	Atualizações menores cuidadosas, suíte de testes
`@acme/*` Interno	workspace ou semver publish
Transitiva	Controlada apenas via lockfile
devDependencies	Fixe versões principais; atualize com toolchain

Notas de TypeScript

@types/* devDeps rastreiam DefinitelyTyped; remova quando o pacote enviar seus próprios tipos (Express 5).
Alinhe @types/node com Node 24.

Armadilhas

Adicionar lodash para uma única função - Custo de dependência de 4MB para sempre. Correção: JS nativo ou utilitário de 10 linhas em packages/utils.
Ignorar auditoria porque "não há correção" - Dívida silenciosa por meses. Correção: ticket de exceção com controle compensatório e expiração.
Dependência do GitHub no branch master - Fonte mutável não fixada. Correção: release semver do npm ou SHA de tag git.
Bibliotecas duplicadas sobrepostas - moment e date-fns e dayjs. Correção: escolha única da biblioteca de data padrão da organização.
Pacotes com script de instalação sem revisão - Risco de cadeia de suprimentos. Correção: bloqueio na política do Socket/PR.

Alternativas

Alternativa	Use Quando	Não Use Quando
Vender um pequeno trecho MIT	Função única, licença clara	Código grande ou GPL
Proxy de registro privado	Cache e escaneie todos os tarballs	Projeto solo de hobby
Política zero-dep para libs	Pacotes publicados	Aplicativos internos com dependências normais

FAQs

Fixar versões exatas em package.json?

Aplicativos usam intervalos + lockfile. Bibliotecas usam intervalos para consumidores; evite fixações exatas, a menos que necessário.

Como detectar pacotes abandonados?

Verifique a última data de publicação, issues abertas, downloads npm; Socket sinaliza indicadores de não manutenção.

Podemos usar dependências GPL?

Geralmente evite em serviços proprietários; revisão legal necessária para copyleft.

Quantas dependências diretas são muitas?

Sem número fixo; questione cada adição. >50 dependências diretas justificam revisão periódica de knip e auditoria.

Campo overrides em package.json?

Use com moderação para forçar um patch transitivo; documente o motivo no PR; overrides confundem o Renovate.

Avisos de dependência de par?

Corrija antes de mesclar; plugins Nest/ESLint frequentemente precisam de instalações de par explícitas.

Workers devem compartilhar lockfile com a API?

Monorepo: sim, lockfile raiz único. Polyrepo: auditorias independentes por deploy.

Quão rápido corrigir CVE crítico?

SLA de 24-48h para RCE alcançável na pilha HTTP; rastreie no quadro de incidentes.

DevDependencies são auditadas?

Sim, para risco da máquina do desenvolvedor; também execute npm ci --omit=dev audit para o grafo de produção.

Processo de substituição de pacote obsoleto?

ADR ou ticket, branch de migração, remova a dependência antiga no mesmo PR da nova implementação.

Relacionado

Checklist de Regras de Projeto Node - regra 10
Cadeia de Suprimentos: npm audit & Socket - checklist de auditoria
Regras de Segurança - segurança em nível de aplicativo

Versões da Stack: 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.

Regras de Dependência

Buscar na documentação

Regras de Dependência