Melhores Práticas de Configuração de Projeto

Padrões para repositórios de serviços Node que integram rapidamente, constroem em CI e implantam de forma previsível.

Como Usar Esta Lista

• Aplique ao criar repositórios a partir de templates ou geradores.
• Revise durante revisões de arquitetura antes de adicionar um segundo deployable.
• Aplique o layout e os scripts via CI de template, não por convenções informais.

A - Layout do Repositório

• Use src/ para código de tempo de execução e um local de teste dedicado. Escolha test/ ou *.test.ts colocados juntos, não ambos.
• Um deployable principal por pasta de aplicativo em monorepos. apps/billing-api mapeia para uma imagem de contêiner.
• Mantenha a configuração na raiz do repositório ou na raiz do aplicativo de forma consistente. A descoberta de tsconfig, ESLint e Dockerfile é importante.
• Confirme .env.example, nunca segredos. Documente cada variável necessária com padrões seguros.
• Inclua rotas health (e opcionalmente ready) desde o primeiro dia. Load balancers e orquestradores precisam delas.

B - TypeScript e Scripts

• Divida tsconfig.json e tsconfig.build.json. Verifique os tipos dos testes; emita apenas src/ para dist/.
• Use a resolução de módulo NodeNext no Node 24. Corresponde ao comportamento import do ESM em produção.
• Exporte createApp() (ou equivalente) de servidores. Permite testes de integração HTTP sem vincular portas.
• Scripts: dev, build, start, test, typecheck. Mesmos comandos localmente e em CI.
• Execute start de produção contra JS compilado. Não tsx em contêineres.

C - Docker e Tempo de Execução

• Fixe o patch do Node no Dockerfile (node:24.18.0-alpine). Alinhe com engines em package.json.
• Builds multi-stage: deps, build, runtime. A imagem de produção exclui TypeScript e devDependencies.
• Copie o lockfile antes do código-fonte para o cache de camada. A reconstrução da camada npm ci ocorre apenas quando as dependências mudam.
• Defina NODE_ENV=production na camada de runtime. Frameworks e verbosidade de log dependem disso.
• Documente a porta exposta e o caminho de health no README. Corresponde às sondas K8s e arquivos compose.

D - Monorepo e Scaffolding

• Código compartilhado em packages/, deployables em apps/. Aplicativos nunca importam aplicativos irmãos diretamente.
• Mantenha um repositório de template interno com CI. Novos serviços herdam os pins atuais de Express/Fastify/Nest.
• Use Turborepo ou Nx quando 3+ pacotes precisarem de orquestração. Scripts npm simples param de escalar.
• Filtre por caminho os deploys de CI por serviço. Mudanças de API não relacionadas não devem reimplantar o faturamento.
• Versionar o pacote de contratos internos com disciplina de quebra de compatibilidade. Mudanças no esquema Zod afetam vários aplicativos.

E - Documentação e Governança

• Início rápido no README: npm ci, cópia de env, npm run dev. Três passos para executar o servidor.
• Registre a escolha do framework no ADR para novos serviços. Express vs Fastify vs Nest não é arbitrário por repositório.
• Adicione um teste de exemplo no scaffold. A CI nunca envia com npm test vazio passando trivialmente.
• .gitignore cobre node_modules, dist, .env, coverage. Evite commits acidentais.
• Renomeie e limpe placeholders de template antes do primeiro deploy. Nomes de serviço padrão se propagam para métricas e logs.

FAQs

Relacionado

• Noções Básicas de Configuração de Projeto - exemplos de layout
• Scaffolding de APIs - templates e CLIs
• Monorepo Multi-Serviço - regras de app vs pacote

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.