Melhores Práticas de Gerenciadores de Pacotes

Regras que mantêm as instalações reproduzíveis, auditorias significativas e monorepos manteníveis.

Como Usar Esta Lista

• Aplique em novos repositórios antes do primeiro deploy em produção.
• Revise ao adicionar workspaces ou trocar npm/pnpm/Yarn.
• Imponha via CI (npm ci, portões de auditoria) em vez de lembretes no README.
• Verifique itens durante PRs de atualização de dependências e atualizações do Node da plataforma.

A - Política de Gerenciador e Lockfile

• Um gerenciador de pacotes por repositório. Lockfiles mistos garantem grafos node_modules divergentes.
• Commite o lockfile para cada aplicação e serviço implantável. Instalações de CI e Docker reproduzíveis dependem disso.
• Use npm ci em CI, não npm install. Evita desvios silenciosos de resolução a cada execução do pipeline.
• Documente o gerenciador escolhido no README. Inclua comandos de instalação, bootstrap e solução de problemas.
• Fixe o Node em CI e Docker para corresponder a engines. Ex: 24.18.0, não flutuante 24.x apenas.

B - Dependências e Scripts

• Separe dependencies e devDependencies corretamente. TypeScript, ESLint e runners de teste são apenas para desenvolvimento.
• Mantenha scripts como o contrato de automação. npm test, npm run build e npm run typecheck funcionam localmente e em CI.
• Evite scripts pesados de postinstall. Instalações lentas prejudicam todos os desenvolvedores e todos os jobs de CI cacheados.
• Use prepublishOnly para portões de publicação. Testes e typecheck rodam antes que os tarballs cheguem ao registro.
• Prefira CLIs fixadas no lockfile em vez de npx puro em scripts. tsx e eslint pertencem a devDependencies.

C - Workspaces e Monorepos

• Use workspace:* para pacotes internos. Link simbólico de libs locais em vez de caminhos file: manuais.
• Compile pacotes compartilhados antes dos dependentes. Ordene tarefas em scripts raiz ou use Turborepo dependsOn.
• Exporte através de exports do pacote, não imports relativos profundos. ../../packages/foo/src entre pacotes quebra limites.
• Um lockfile raiz para todo o monorepo. Lockfiles por pacote anulam os benefícios do linking de workspace.
• Nomeie workspaces com escopo consistente. @acme/api, @acme/shared esclarece a propriedade.

D - Segurança e Conformidade

• Execute npm audit --audit-level=high em cada PR de dependência. Bloqueie a mesclagem até que seja corrigido ou excecionado com expiração.
• Revise as alterações de script de instalação nas diferenças de dependência. Adições em postinstall são de alto risco.
• Ative a proveniência para bibliotecas internas publicadas. Consumidores verificam artefatos compilados em CI.
• Defina engine-strict=true em .npmrc. Node não suportado falha na instalação, não em produção.
• Automatize atualizações de dependência com PRs agrupados de Renovate/Dependabot. Lotes de atualização menores e testáveis.

E - Publicação e Versionamento

• Use lista de permissão estrita de files ao publicar. Nunca envie testes, segredos .env.example ou src/ crus não intencionalmente.
• Siga o semver para pacotes publicados. Mudanças de API que quebram exigem bumps maiores.
• Envie JS compilado e .d.ts para bibliotecas TypeScript. Consumidores não devem compilar seu código-fonte.
• Marque releases em git ao publicar. npm version mais CI de publicação mantêm o registro e a origem alinhados.
• Deprecie versões ruins em vez de despublicar. npm deprecate avisa os consumidores sem quebrar lockfiles.

FAQs

Relacionados

• Noções Básicas de Gerenciadores de Pacotes - Seleção de npm, pnpm, Yarn
• Lockfiles e Instalações Reproduzíveis - Detalhes de npm ci
• Cadeia de Suprimentos: npm audit & Socket - Portões de mesclagem

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.