CommonJS (require)

CommonJS (require, module.exports) alimentou o Node por anos - você ainda o mantém em pacotes legados, carregadores de configuração e shims .cjs enquanto novos serviços padronizam em ESM.

Receita

// config.cjs
const path = require('node:path');
 
module.exports = {
  port: Number(process.env.PORT ?? 3000),
  root: __dirname,
  resolve: (p) => path.join(__dirname, p),
};

const config = require('./config.cjs');

Quando usar isso:

• Manutenção de dependências npm mais antigas que exportam apenas CJS
• Arquivos de configuração do Jest ainda em require em repositórios brownfield
• Hooks de ferramentas .cjs (jest.config.cjs, prettier.config.cjs)
• Pontos de entrada ESM que usam pontes createRequire

Exemplo Funcional

// circular-a.cjs
const b = require('./circular-b.cjs');
module.exports = {
  name: 'A',
  bName: () => b.name,
};

// circular-b.cjs
const a = require('./circular-a.cjs');
module.exports = {
  name: 'B',
  aName: () => a.name,
};

// main.cjs
const a = require('./circular-a.cjs');
console.log(a.name, a.bName()); // A B - exportações parciais durante a inicialização circular

// esm-dirname-polyfill.cjs - padrão que importadores ESM evitam usando import.meta.url
const { fileURLToPath } = require('node:url');
// Necessário apenas ao ensinar diferenças entre CJS e ESM

O que isso demonstra:

• require retorna module.exports - atribuições substituem todo o objeto de exportação
• Requerimentos circulares retornam module.exports parciais até que os módulos terminem de inicializar
• __dirname é o diretório do arquivo CJS atual - sem equivalente ESM sem import.meta.url
• Cache: um segundo require('./same') retorna a mesma referência de objeto

Mergulho Profundo

Como Funciona

• O Node resolve o caminho, envolve o arquivo em uma função e armazena module.exports em cache em require.cache.
• exports.foo = 1 é açúcar para module.exports.foo até que você reatribua module.exports = ....
• Módulos embutidos carregam primeiro - require('node:fs') não acessa o disco.
• JSON pode ser require('./x.json') em CJS - ESM precisa de readFile + JSON.parse ou padrões de asserções de importação.

Padrões de exports

Notas de TypeScript

// Consumindo CJS de TS com esModuleInterop
import config from './config.cjs';
// ou
import { createRequire } from 'node:module';
const require = createRequire(import.meta.url);
const cfg = require('./config.cjs') as { port: number };

Armadilhas

• Reatribuir exports após module.exports = - falha. Correção: mutate module.exports apenas uma vez.
• Surpresas com dependências circulares - importações indefinidas durante a inicialização. Correção: require preguiçoso dentro de funções ou refatorar o módulo compartilhado.
• Assumir __dirname em ESM - ReferenceError. Correção: import.meta.url + fileURLToPath.
• Mutar singletons requeridos - todos os importadores veem as mudanças. Correção: tratar exportações como estado compartilhado intencionalmente ou congelá-las.
• Caminhos profundos ../../../ - movimentos frágeis. Correção: migrar para ESM com mapa exports ou aliases de caminho em tsconfig.

Alternativas

FAQs

Relacionados

• ES Modules (import) - o caminho a seguir
• Interop CJS ↔ ESM - estratégias de ponte
• package.json type & exports - fronteiras de pacotes
• Noções Básicas de Módulos - introdução lado a lado

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.