Saída dupla de pacotes ESM e CJS

ESM (módulos ECMAScript) é o padrão oficial de módulos do JavaScript, que usa a sintaxe import e export. ESM pode ser analisado estaticamente — os empacotadores conseguem determinar no momento da compilação exatamente quais exportações são usadas, permitindo a eliminação de código não utilizado. Os navegadores modernos e o Node.js oferecem suporte nativo a ESM.

CJS (CommonJS) usa a sintaxe require() e module.exports. Esse foi o sistema de módulos original do Node.js e ainda é necessário para a compatibilidade com ambientes mais antigos do Node.js, com o Jest (que historicamente usava CJS) e com código que usa require(). CJS é avaliado dinamicamente, o que dificulta a eliminação de código não utilizado.

Um pacote npm moderno deve distribuir ESM e CJS para maximizar a compatibilidade. Consumidores de ESM (Vite, Next.js e empacotadores modernos) obtêm importações otimizáveis por eliminação de código não utilizado. Consumidores de CJS (scripts mais antigos do Node.js e Jest sem configuração) obtêm compatibilidade com require(). O campo exports de package.json informa ao Node e aos empacotadores qual formato usar.

O campo exports em package.json é a forma moderna de definir pontos de entrada condicionais. Exemplo: { '.': { 'import': './dist/esm/index.js', 'require': './dist/cjs/index.js', 'types': './dist/esm/index.d.ts' } }. Empacotadores e o Node.js 12 ou posterior leem exports para selecionar automaticamente o formato correto.

Ferramentas mais antigas não entendem o campo de exportações. Para manter a compatibilidade, defina também: principal apontando para a saída CJS (alternativa de carregamento legada do Node), e módulo apontando para a saída ESM (uma indicação para webpack/Rollup, não padronizada, mas amplamente compatível). Ferramentas modernas preferem exportações; ferramentas legadas recorrem a principal/módulo.

Definir "type": "module" em package.json faz com que todos os arquivos .js do pacote sejam tratados como ESM. Se você distribuir os dois formatos, precisará usar extensões explícitas: use .mjs para arquivos ESM e .cjs para arquivos CJS quando o tipo for módulo, ou o contrário. O tsup faz isso automaticamente.

Usar explicitamente as extensões de arquivo .mjs (ESM) e .cjs (CJS) marca o formato independentemente do campo de tipo. Isso evita ambiguidades. O tsup pode gerar: index.js (ESM) e index.cjs (CJS) quando o formato for ['esm', 'cjs'] e nenhum campo de tipo estiver definido, seguindo a convenção mais comum.

Quando um pacote fornece os formatos ESM e CJS, o empacotador do consumidor pode carregar as duas versões no mesmo processo — por exemplo, a versão ESM para a aplicação principal e a versão CJS para um teste do Jest. Se o pacote tiver estado no nível do módulo (como um contexto do React), as duas instâncias terão estados independentes. Esse é o risco dos pacotes duplos.

Para reduzir esse risco: mantenha o estado no nível do módulo fora da sua biblioteca (sem padrões de instância única), use as condições de exports com precisão para garantir que apenas um formato seja carregado e documente que os testes devem configurar o empacotador para usar ESM. Esse risco é relevante principalmente para bibliotecas com instâncias únicas compartilhadas.

Verifique se os dois formatos funcionam após a compilação. Teste CJS: node -e "const lib = require('./dist/cjs/index.js'); console.log(lib)". Teste ESM: node --input-type=module --eval "import { Component } from './dist/esm/index.js'; console.log(Component)". Ambos devem ser resolvidos sem erros antes da publicação.

O campo de exportações oferece suporte a vários pontos de entrada: { '.': { import: './dist/esm/index.js', require: './dist/cjs/index.js' }, './utils': { import: './dist/esm/utils.js', require: './dist/cjs/utils.js' } }. Os consumidores podem então importar de 'your-lib' ou 'your-lib/utils' e obter o formato correto.

Qual é a finalidade principal do campo exports no package.json de uma biblioteca?

ESM usa importação/exportação e permite a eliminação de código não utilizado. CJS usa o carregamento de módulos para garantir compatibilidade com o Node.js. Distribua os dois formatos por meio do campo de exportações de package.json, com condições para importação e carregamento. Alternativas legadas: principal (CJS) e módulo (ESM). Use extensões .mjs/.cjs ou o tipo: módulo para marcar explicitamente o formato. Teste os dois formatos com a CLI do node após a compilação. Tenha cuidado com o risco dos pacotes duplos quando houver estado em instâncias únicas.