CommonJS (require)

CommonJS (require, module.exports) impulsó Node durante años; todavía lo mantienes en paquetes heredados, cargadores de configuración y shims .cjs, mientras que los nuevos servicios se estandarizan en ESM.

Receta

// 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');

Cuándo usarlo:

• Mantener dependencias npm antiguas que solo exportan CJS
• Archivos de configuración de Jest que aún usan require en repositorios existentes
• Hooks de herramientas .cjs (jest.config.cjs, prettier.config.cjs)
• Puentes createRequire desde puntos de entrada ESM

Ejemplo de funcionamiento

// 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 - exportaciones parciales durante la inicialización circular

// esm-dirname-polyfill.cjs - patrón que los importadores de ESM evitan usando import.meta.url
const { fileURLToPath } = require('node:url');
// Solo es necesario al enseñar las diferencias entre CJS y ESM

Lo que esto demuestra:

• require devuelve module.exports: las asignaciones reemplazan todo el objeto de exportación
• Los require circulares devuelven module.exports parciales hasta que los módulos terminan de inicializarse
• __dirname es el directorio del archivo CJS actual; no hay equivalente en ESM sin import.meta.url
• Caché: el segundo require('./same') devuelve la misma referencia de objeto

Análisis profundo

Cómo funciona

• Node resuelve la ruta, envuelve el archivo en una función y almacena module.exports en require.cache.
• exports.foo = 1 es azúcar sintáctico para module.exports.foo hasta que reasignes module.exports = ....
• Los módulos incorporados se cargan primero: require('node:fs') no accede al disco.
• JSON puede ser require('./x.json') en CJS; ESM necesita readFile + JSON.parse o patrones de aserciones de importación.

Patrones de exportación

Notas de TypeScript

// consumir CJS desde TS con esModuleInterop
import config from './config.cjs';
// o
import { createRequire } from 'node:module';
const require = createRequire(import.meta.url);
const cfg = require('./config.cjs') as { port: number };

Errores comunes

• Reasignar exports después de module.exports = - falla. Solución: muta module.exports solo una vez.
• Sorpresas con dependencias circulares - importaciones indefinidas a mitad de la inicialización. Solución: require perezoso dentro de funciones o refactorizar el módulo compartido.
• Asumir __dirname en ESM - ReferenceError. Solución: import.meta.url + fileURLToPath.
• Mutar singletons requeridos - todos los importadores ven los cambios. Solución: tratar las exportaciones como estado compartido intencionalmente o congelar.
• Rutas profundas ../../../ - movimientos frágiles. Solución: migrar a ESM con mapa de exports o alias de ruta en tsconfig.

Alternativas

Preguntas frecuentes

Relacionado

• Módulos ES (import) - el camino a seguir
• Interoperabilidad CJS ↔ ESM - estrategias de puente
• package.json type & exports - límites del paquete
• Conceptos básicos de módulos - introducción lado a lado

Versiones de la pila: Esta página fue escrita para Node.js 24.18.0 (LTS activa), npm 10+, TypeScript 5.6+, Express 5, Fastify 5 y NestJS 11.