Boas Práticas Fundamentais do Node.js

Uma lista de verificação para executar serviços Node.js com segurança em produção - disciplina de versão, higiene de ambiente e respeito ao modelo de thread única.

Como Usar Esta Lista

• Percorra de cima para baixo antes de cada deploy em produção ou upgrade de LTS.
• Trate itens não verificados como bloqueadores de release, a menos que documentados em uma exceção de ADR.
• Revise trimestralmente ou quando o Node publicar um release de segurança.
• Combine com listas específicas de seção (event loop, módulos, TypeScript) para auditorias mais profundas.

A - Disciplina de Versão e Runtime

• Execute LTS Ativa (Node 24.18.0) ou uma janela LTS de Manutenção aprovada. Releases Current ímpares são apenas para desenvolvimento.
• Fixe engines em package.json e aplique em CI. Use engine-strict=true ou um script de gate de pré-instalação.
• Commite .nvmrc ou .node-version e combine com as imagens base do Docker. node:24.18.0-bookworm-slim, não node:latest.
• Acompanhe as datas de fim da LTS no calendário da equipe. Agende upgrades 6 meses antes do Fim de Vida.
• Registre process.version na inicialização e exponha em /health. Acelera a triagem de incidentes quando frotas divergem.

B - Higiene de Projeto e Módulos

• Por padrão, novos serviços devem usar ESM ("type": "module"). Documente qualquer exceção de CJS com um ADR.
• Use o prefixo node: para imports embutidos. import fs from 'node:fs/promises' clarifica a intenção.
• Prefira fetch embutido, node:test e node:assert antes de equivalentes do npm. Menos superfícies de cadeia de suprimentos.
• Mantenha package-lock.json committado e use npm ci em CI. Instalações reproduzíveis entre máquinas.
• Audite addons nativos após cada bump de major do Node. bcrypt, sharp e similares devem recompilar limpo.

C - Configuração e Globais

• Valide variáveis de ambiente na inicialização com um schema (Zod). Falhe rapidamente antes de aceitar tráfego.
• Nunca modifique process.env após o boot, exceto em testes. Trate env como configuração imutável.
• Evite armazenar dados de escopo de requisição em variáveis globais. Use AsyncLocalStorage para contexto de requisição.
• Defina NODE_ENV=production em ambientes implantados. Algumas bibliotecas mudam o comportamento com base nisso.
• Não registre segredos, tokens ou dumps completos de process.env. Redija em logs estruturados.

D - Segurança e Operações de Processo

• Manipule SIGTERM e SIGINT para desligamento gracioso. Feche servidores e pools de DB antes de sair.
• Trate rejeições não tratadas como fatais em produção. Use process.on('unhandledRejection') para registrar e sair.
• Limite o tamanho do corpo JSON no proxy reverso e na camada de aplicação. Proteja o event loop de JSON.parse enormes.
• Execute com um usuário não root em contêineres. Imagens oficiais do Node fornecem o usuário node.
• Habilite --trace-warnings e --trace-deprecation em CI. Capture dívidas de upgrade antes da produção.

E - Observabilidade e Documentação

• Marque os docs oficiais para seu major fixado (v24.x). Não confie em posts de blog desatualizados.
• Capture avisos do Node nos logs durante canários de deploy. Depreciações preveem quebras de major futuro.
• Saiba como gerar um relatório de diagnóstico (process.report). Pratique antes da primeira página às 3 da manhã.
• Documente ADRs de runtime ao avaliar Bun/Deno. O padrão permanece Node até que evidências digam o contrário.
• Mantenha runbooks vinculados do README do repositório. Inclua comandos de verificação de versão e rollback.

FAQs

engine-strict=true

Relacionados

• Instalação e Gerenciamento de Versão - ferramentas para aplicar versões
• Política de Release e LTS do Node.js - detalhes do ciclo de vida da LTS
• Como o Node.js Funciona - por que globais e bloqueio importam
• Melhores Práticas do Event Loop - regras de desempenho assíncrono

Versões de 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.