Módulos ES versus CommonJS no Node.js

O que é

CommonJS (CJS) é o sistema de módulos original do Node: require() carrega o módulo de forma síncrona, em tempo de execução, e o módulo exporta tudo o que atribuir a module.exports. Os módulos ES (ESM) são o padrão da linguagem: import e export são estáticos e resolvidos antes de o corpo do módulo ser executado, o carregamento é assíncrono, await de nível superior é permitido e import.meta traz metadados do módulo. O Node decide por arquivo: .mjs é sempre ESM, .cjs é sempre CJS e .js segue o campo "type" do package.json mais próximo. Sem o campo "type", a documentação de pacotes considera o arquivo ambíguo: as versões atuais do Node o executam primeiro como CommonJS e, se o parser encontrar sintaxe de módulo ES, o reavaliam como módulo ES (detecção de sintaxe); versões mais antigas o tratam simplesmente como CommonJS. A documentação de ESM lista o que falta no ESM (require, module.exports, __filename, __dirname) e os substitutos: import.meta.filename, import.meta.dirname, import.meta.resolve() e module.createRequire(). O ESM pode importar CommonJS (a importação padrão é module.exports), e as versões atuais do Node conseguem usar require() em um módulo ES, desde que o seu grafo não contenha await de nível superior.

Por que importa

Misturar os dois sistemas está por trás dos erros de inicialização mais comuns em projetos Node: "Cannot use import statement outside a module", ERR_REQUIRE_ESM, exports is not defined. Test runners, a saída do TypeScript e bundlers têm cada um a sua própria configuração de módulos, e uma incompatibilidade falha em tempo de execução, não na compilação.

Como aplicar

• Código novo: defina "type": "module" no package.json e escreva ESM em todo o projeto; dê a extensão .cjs aos poucos arquivos que precisam continuar em CommonJS.
• Importações relativas em ESM devem incluir a extensão do arquivo (./util.js, ./dir/index.js); o resolvedor não tenta adivinhar.
• JSON é importado com um atributo: import cfg from "./cfg.json" with { type: "json" }.
• Bibliotecas que distribuem os dois formatos: declare "exports" com as condições import e require, e antes disso leia a documentação de pacotes e o repositório de exemplos ligado a ela sobre pacotes duais; um pacote carregado pelos dois pontos de entrada passa a existir duas vezes, com estado de módulo separado (o risco do pacote dual, ou dual package hazard).
• Em navegadores, scripts de módulo devem ser servidos com um tipo MIME de JavaScript, como text/javascript; a MDN documenta o erro de verificação estrita de tipo MIME para arquivos .mjs servidos de outra forma.

Armadilhas

Importações circulares se comportam de modo diferente: as ligações (bindings) do ESM são vivas, mas podem estar não inicializadas quando lidas cedo demais. Usar require() em um ESM que emprega await de nível superior lança ERR_REQUIRE_ASYNC_MODULE; use import() no lugar. Um compilador que gera chamadas require em um pacote com "type": "module" produz código que falha ao carregar; mantenha a configuração de saída de módulos do compilador alinhada com o ambiente de execução.