Boas Práticas de TypeScript em Node.js

TypeScript compensa quando verificações rigorosas em tempo de compilação encontram validação em tempo de execução nas fronteiras - não quando any vaza através de resultados de ORM e corpos de requisição.

Como Usar Esta Lista

• Aplique a cada novo serviço e a cada módulo migrado que sai de allowJs.
• Bloqueie PRs que adicionam any ou @ts-ignore sem justificativa em ticket.
• Emparelhe com tsc --noEmit e testes em CI - tipos sem testes ainda enviam bugs.
• Revise ao atualizar versões principais do TypeScript para novas flags rigorosas.

A - Configuração do Compilador e do Projeto

• Habilite strict: true para todos os novos projetos. Adicione flags mais rigorosas (noUncheckedIndexedAccess) quando a equipe estiver pronta.
• Use module / moduleResolution: NodeNext no Node 24 ESM. Corresponde ao resolvedor em tempo de execução.
• Execute tsc --noEmit em CI em cada PR. tsx sozinho não verifica tipos.
• Emita dist/ para contêineres de produção. CMD ["node", "dist/main.js"] - sem tsx na imagem de produção.
• Fixe typescript e @types/node em majors compatíveis. Alinhe @types/node com Node 24.

B - Fronteiras e Tempo de Execução

• Valide process.env com Zod na inicialização. Falhe antes de escutar em uma porta.
• Analise corpos, queries e parâmetros HTTP com schemas. Nunca use as Foo em req.body.
• Derive tipos com z.infer - sem interfaces duplicadas. Fonte única de verdade.
• Mapeie entidades de banco de dados para DTOs explicitamente. Não exporte modelos ORM para clientes.
• Trate respostas de SDK externas como unknown até serem analisadas. Mesmo de fornecedores confiáveis.

C - Estilo de Código e Segurança

• Prefira import type para imports apenas de tipos. Habilite verbatimModuleSyntax em novos repositórios.
• Evite any - use unknown + estreitamento. ESLint @typescript-eslint/no-explicit-any como erro.
• Limite asserções não nulas (!) a testes. Código de produção usa guards ou Zod.
• Use uniões discriminadas para tipos de resultado. { ok: true, value } | { ok: false, error }.
• Não use @ts-ignore - use @ts-expect-error com ticket e data de remoção.

D - Integração com Frameworks

• Aumente Request do Express apenas para campos transversais. Genéricos por rota para corpo/parâmetros.
• Use schemas Fastify ou type provider Zod. Uma fonte de validação para rotas Fastify 5.
• Tipifique handlers assíncronos como retorno Promise<void>. Garanta que erros alcancem os hooks de erro do framework.
• Compartilhe pacotes DTO - não internos do servidor - com o frontend. Padrão @acme/api-types.
• DTOs NestJS: valide com pipes, não apenas com decoradores. class-validator ou Zod na fronteira.

E - Migração e Manutenção

• Rachet: sem novos arquivos .js em diretórios tipados. allowJs é temporário.
• Converta utilitários folha antes dos arquivos de rota. Migração de baixo para cima reduz a instabilidade do grafo.
• Adicione tipos a suítes node:test precocemente. Testes travam o comportamento durante a renomeação de JS para TS.
• Revise as notas de lançamento do TypeScript para novas opções rigorosas trimestralmente. Opte por elas deliberadamente.
• Mantenha o pacote de tipos compartilhados livre de imports node:*. Seguro para bundlers React.

FAQs

Relacionados

• Zod nas Fronteiras - validação em tempo de execução
• Noções Básicas de TypeScript em Node.js - tsconfig inicial
• Tipagem Gradual em Código Existente - playbook de migração
• Verificação de Tipos em CI - aplicação

Versões da Stack: Esta página foi escrita para Node.js 24.18.0 (LTS Ativo), npm 10+, TypeScript 5.6+, Express 5, Fastify 5 e NestJS 11.