Boas Práticas de Módulos

Os limites dos módulos moldam a capacidade de implantação e os refators - padronize em ESM, exports explícitos e dependências honestas no package.json, a menos que um ADR documente uma exceção de módulo duplo.

Como Usar Esta Lista

• Aplique a cada novo pacote em um monorepo e a cada biblioteca publicável.
• Durante a migração CJS, verifique apenas os itens marcados como relevantes - não publique em modo duplo sem uma data de desativação.
• Emparelhe com Knip ou dependency-cruiser no CI para detecção de dependências fantasmas.
• Revise quando TypeScript ou Node alterarem os padrões de resolução de módulos.

A - Escolha do Sistema de Módulos

• Defina "type": "module" em novos pacotes de aplicação. CJS apenas para configurações .cjs e shims legados.
• Um sistema de módulos por pacote implantável, quando possível. CJS/ESM duplo apenas para bibliotecas publicadas com testes de interoperabilidade documentados.
• Use extensões .mjs / .cjs ao misturar sistemas em um pacote. Nunca confie na análise ambígua de .js.
• Documente exceções de módulo duplo em um ADR com data de desativação. O modo duplo é migração, não arquitetura.
• Prefira o prefixo node: em importações built-in. Evite sombreamento e esclareça a intenção.

B - Higiene do package.json

• Defina "exports" para bibliotecas e pacotes compartilhados de monorepo. Bloqueie importações profundas em src/.
• Declare toda importação de especificador nu em dependencies. Não confie em dependências fantasmas elevadas.
• Aponte exports para dist/ compilado, não para o código-fonte TypeScript. Consumidores executam JS que corresponde à resolução do Node.
• Exporte "./package.json" apenas quando a ferramenta exigir. Mantenha a superfície mínima caso contrário.
• Use o protocolo de workspace (workspace:*) consistentemente em monorepos. Trave versões na publicação.

C - Estilo de Importação

• Prefira exportações nomeadas em vez de padrão para bibliotecas. Melhores refators e clareza de tree shaking.
• Use import type para importações apenas de tipos. Habilita verbatimModuleSyntax e bundles mais limpos.
• Inclua extensões .js em caminhos de importação ESM relativos. Corresponde à emissão e tempo de execução do NodeNext.
• Limite import() dinâmico a plugins e caminhos de código opcionais. Mantenha o grafo principal estático e analisável.
• Evite dependências circulares entre barrels. Importe diretamente de módulos folha.

D - Alinhamento com TypeScript

• Use "module": "NodeNext" e "moduleResolution": "NodeNext". Corresponde ao resolvedor ESM do Node 24.
• Não assuma que os caminhos tsconfig corrigem o tempo de execução. Emita caminhos corretos ou use ferramentas de build.
• Habilite verbatimModuleSyntax para novos projetos. Separa explicitamente as importações de tipo.
• Teste node dist/main.js no CI, não apenas tsx src. Captura erros de extensão e exportação.
• Envie .d.ts ao lado do JS emitido com a condição exports de tipos correspondente.

E - Monorepo e Publicação

• Execute npm pack --dry-run antes de publicar. Verifique se files e exports incluem apenas os artefatos pretendidos.
• Teste de integração tanto import quanto require se estiver publicando em modo duplo. Evite regressões de perigos de pacotes duplos.
• Fixe dependências internas do workspace em versões compatíveis na liberação. Evite suposições apenas de symlink em tarballs de produção.
• Use mapas de importação #internal para módulos privados do pacote. Nunca exponha caminhos # via exports.
• Procure por ERR_PACKAGE_PATH_NOT_EXPORTED em aplicativos consumidores após o aperto das exportações. Comunique alterações que quebram a compatibilidade.

FAQs

Relacionados

• Tipo e exports do package.json - configuração de exports
• Algoritmo de Resolução de Módulos - como o Node resolve importações
• Interoperabilidade CJS ↔ ESM - pontes de migração
• Noções Básicas de TypeScript no Node - padrões tsconfig

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.