Melhores Práticas para Bibliotecas Essenciais

Q: Pacotes internos devem encapsular esquemas zod?

Sim para contratos entre serviços (@acme/contracts). Serviços importam esquemas compartilhados; não duplique a validação por API.

Regras que mantêm as dependências npm de fácil manutenção, seguras e consistentes em todos os serviços Node.js.

Como Usar Esta Lista

Aplique ao iniciar uma nova API ou serviço de worker.
Revise durante os sprints trimestrais de higiene de dependências.
Aplique por meio de gates de auditoria de CI e caixas de seleção no template de PR.
Verifique os itens ao integrar uma biblioteca ou desativar uma antiga.

A - Seleção e Padrões

Documente a pilha essencial padrão em CONTRIBUTING.md. zod, pino, got ou axios, Luxon, BullMQ + ioredis, a menos que o ADR diga o contrário.
Avalie novos pacotes com um checklist escrito. Manutenção, resposta de segurança, licença, peso transitivo.
Exija link de ADR para bibliotecas não padrão. Mínimo de um parágrafo em docs/adr/.
Prefira built-ins do Node 24 primeiro. fetch, node:test, node:crypto antes de equivalentes npm.
Uma biblioteca por preocupação por serviço. Sem sobreposição de moment + Luxon + date-fns.
Rejeite pacotes com descobertas de auditoria de alto nível não mitigadas. Ticket de exceção com data de expiração.

B - Fixação e Atualizações

Faça commit do lockfile em cada alteração de dependência. package-lock.json ou equivalente pnpm/yarn.
Use npm ci em CI, nunca npm install. Grafos reproduzíveis em cada execução de pipeline.
Fixe o Node em engines para Active LTS. 24.18.0 alinhado com .nvmrc e imagem base do Docker.
Agrupe PRs do Renovate/Dependabot semanalmente. Menor raio de explosão do que mega-atualizações mensais.
Execute typecheck e suíte de testes completa em PRs apenas de lockfile. Quebras transitivas acontecem sem edições de dependência direta.
Alinhe versões de pacotes de workspace compartilhados. Dependências de pares @acme/shared-* correspondem às dependências do serviço.

C - Segurança e Cadeia de Suprimentos

Execute npm audit --audit-level=high em cada PR. Bloqueie a mesclagem até que seja corrigido ou excecionado.
Revise scripts de instalação em diffs de lockfile. Adições de postinstall são de alto risco.
Ative a proveniência para pacotes internos publicados. Consumidores verificam artefatos construídos em CI.
Escaneie com Socket ou similar para risco proativo. Além da auditoria apenas de CVE.
Sem segredos em dependências ou .env commitados. Use injeção de plataforma e gerenciadores de segredos.
Minimize a contagem de add-ons nativos. Cada add-on é uma superfície de build e cadeia de suprimentos.

D - Operações por Biblioteca

Zod apenas nas fronteiras. HTTP, env, payloads de fila - não em todas as funções internas.
Pino JSON para stdout em produção. Sem pino-pretty em imagens de produção; redija cabeçalhos de autenticação.
Clientes HTTP: timeouts e retentativas em todas as chamadas de saída. Retentativa idempotente apenas, a menos que existam chaves de idempotência.
Luxon ou UTC explícito para agendamento. Sem new Date("local string") sem offset.
Workers BullMQ como processos separados. Não dentro do loop de eventos do servidor HTTP.
Prefixos de chave Redis separam o cache das chaves de fila. cache: vs prefixo interno do BullMQ.

E - Desativação e Higiene

Desative com janela de migração e proibição de lint para novas importações. Rastreie por repositório em uma issue do GitHub.
Remova deps não utilizadas com depcheck trimestralmente. Pacotes mortos ainda falham na auditoria.
Documente atualizações que quebram no CHANGELOG. Especialmente grandes atualizações de Zod, Fastify, BullMQ.
Reavalie ADRs anualmente. Rotatividade de mantenedores ou melhores built-ins podem tornar as escolhas obsoletas.
Treine revisores nos sinais de alerta de PR de dependência. Bibliotecas duplicadas, falta de lockfile, omissão de auditoria.

FAQs

Quão rigorosa é a pilha padrão?

Padrões são recomendações fortes. Desvios precisam de ADR, não de acordo informal. Exceções expiram quando o ADR é revisitado.

Quando axios vale a pena em vez de got?

Quando a equipe já padronizou interceptadores axios em muitos serviços. Não introduza ambos em um único repositório sem plano de migração.

Pacotes internos devem encapsular esquemas zod?

Sim para contratos entre serviços (@acme/contracts). Serviços importam esquemas compartilhados; não duplique a validação por API.

O que aciona uma remoção de dependência de emergência?

CVE crítico sem patch, versão de pacote comprometida ou script de instalação malicioso. Hotfix branch, bump de lockfile, reimplantar todos os serviços afetados dentro do SLA.

Relacionados

Noções Básicas de Bibliotecas Essenciais - introdução a escolher, fixar, desativar
zod - validação nas fronteiras
pino - logging de produção
got / axios - políticas de HTTP de saída
date-fns / Luxon - fusos horários
bullmq / ioredis - fila + cache
Melhores Práticas de Gerenciadores de Pacotes - política de lockfile

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.

Melhores Práticas para Bibliotecas Essenciais

Regras que mantêm as dependências npm de fácil manutenção, seguras e consistentes em todos os serviços Node.js.

Como Usar Esta Lista

Aplique ao iniciar uma nova API ou serviço de worker.
Revise durante os sprints trimestrais de higiene de dependências.
Aplique por meio de gates de auditoria de CI e caixas de seleção no template de PR.
Verifique os itens ao integrar uma biblioteca ou desativar uma antiga.

A - Seleção e Padrões

Documente a pilha essencial padrão em CONTRIBUTING.md. zod, pino, got ou axios, Luxon, BullMQ + ioredis, a menos que o ADR diga o contrário.
Avalie novos pacotes com um checklist escrito. Manutenção, resposta de segurança, licença, peso transitivo.
Exija link de ADR para bibliotecas não padrão. Mínimo de um parágrafo em docs/adr/.
Prefira built-ins do Node 24 primeiro. fetch, node:test, node:crypto antes de equivalentes npm.
Uma biblioteca por preocupação por serviço. Sem sobreposição de moment + Luxon + date-fns.
Rejeite pacotes com descobertas de auditoria de alto nível não mitigadas. Ticket de exceção com data de expiração.

B - Fixação e Atualizações

Faça commit do lockfile em cada alteração de dependência. package-lock.json ou equivalente pnpm/yarn.
Use npm ci em CI, nunca npm install. Grafos reproduzíveis em cada execução de pipeline.
Fixe o Node em engines para Active LTS. 24.18.0 alinhado com .nvmrc e imagem base do Docker.
Agrupe PRs do Renovate/Dependabot semanalmente. Menor raio de explosão do que mega-atualizações mensais.
Execute typecheck e suíte de testes completa em PRs apenas de lockfile. Quebras transitivas acontecem sem edições de dependência direta.
Alinhe versões de pacotes de workspace compartilhados. Dependências de pares @acme/shared-* correspondem às dependências do serviço.

C - Segurança e Cadeia de Suprimentos

Execute npm audit --audit-level=high em cada PR. Bloqueie a mesclagem até que seja corrigido ou excecionado.
Revise scripts de instalação em diffs de lockfile. Adições de postinstall são de alto risco.
Ative a proveniência para pacotes internos publicados. Consumidores verificam artefatos construídos em CI.
Escaneie com Socket ou similar para risco proativo. Além da auditoria apenas de CVE.
Sem segredos em dependências ou .env commitados. Use injeção de plataforma e gerenciadores de segredos.
Minimize a contagem de add-ons nativos. Cada add-on é uma superfície de build e cadeia de suprimentos.

D - Operações por Biblioteca

Zod apenas nas fronteiras. HTTP, env, payloads de fila - não em todas as funções internas.
Pino JSON para stdout em produção. Sem pino-pretty em imagens de produção; redija cabeçalhos de autenticação.
Clientes HTTP: timeouts e retentativas em todas as chamadas de saída. Retentativa idempotente apenas, a menos que existam chaves de idempotência.
Luxon ou UTC explícito para agendamento. Sem new Date("local string") sem offset.
Workers BullMQ como processos separados. Não dentro do loop de eventos do servidor HTTP.
Prefixos de chave Redis separam o cache das chaves de fila. cache: vs prefixo interno do BullMQ.

E - Desativação e Higiene

Desative com janela de migração e proibição de lint para novas importações. Rastreie por repositório em uma issue do GitHub.
Remova deps não utilizadas com depcheck trimestralmente. Pacotes mortos ainda falham na auditoria.
Documente atualizações que quebram no CHANGELOG. Especialmente grandes atualizações de Zod, Fastify, BullMQ.
Reavalie ADRs anualmente. Rotatividade de mantenedores ou melhores built-ins podem tornar as escolhas obsoletas.
Treine revisores nos sinais de alerta de PR de dependência. Bibliotecas duplicadas, falta de lockfile, omissão de auditoria.

FAQs

Quão rigorosa é a pilha padrão?

Padrões são recomendações fortes. Desvios precisam de ADR, não de acordo informal. Exceções expiram quando o ADR é revisitado.

Quando axios vale a pena em vez de got?

Quando a equipe já padronizou interceptadores axios em muitos serviços. Não introduza ambos em um único repositório sem plano de migração.

Pacotes internos devem encapsular esquemas zod?

Sim para contratos entre serviços (@acme/contracts). Serviços importam esquemas compartilhados; não duplique a validação por API.

O que aciona uma remoção de dependência de emergência?

CVE crítico sem patch, versão de pacote comprometida ou script de instalação malicioso. Hotfix branch, bump de lockfile, reimplantar todos os serviços afetados dentro do SLA.

Relacionados

Noções Básicas de Bibliotecas Essenciais - introdução a escolher, fixar, desativar
zod - validação nas fronteiras
pino - logging de produção
got / axios - políticas de HTTP de saída
date-fns / Luxon - fusos horários
bullmq / ioredis - fila + cache
Melhores Práticas de Gerenciadores de Pacotes - política de lockfile

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.

Melhores Práticas para Bibliotecas Essenciais

Buscar na documentação

Melhores Práticas para Bibliotecas Essenciais