Saltar al contenido
Módulos

CommonJS frente a ESM

Lección 2 de 410 min3 ejercicios

Node.js nació en 2009, seis años antes de que JavaScript tuviera módulos propios, así que inventó los suyos: CommonJS, con require y module.exports. Hoy el estándar es ESM, pero millones de paquetes y proyectos siguen usando CommonJS. Vas a encontrarte con los dos.

CommonJS

// saludos.cjs
const prefijo = "Hola";

function saludar(nombre) {
  return `${prefijo}, ${nombre}`;
}

module.exports = { saludar };   // lo que se exporta es un objeto
// main.cjs
const { saludar } = require("./saludos.cjs");
const fs = require("node:fs");

console.log(saludar("Ana"));
console.log(__dirname);   // la carpeta de este archivo

Las diferencias

CommonJS ES Modules
Sintaxis require() y module.exports import y export
Carga Síncrona, en el momento del require Se analiza antes de ejecutar; admite await de nivel superior
require/import En cualquier lugar, incluso dentro de un if import solo en el nivel superior; import() en cualquier lugar
Lo exportado Un objeto con copias de los valores Enlaces vivos a las variables
Modo estricto Solo si lo pides Siempre
Datos del archivo __dirname, __filename import.meta.dirname, import.meta.filename
En el navegador No Sí

Cómo decide Node.js

Para cada archivo:

  1. .mjs → siempre ESM. .cjs → siempre CommonJS.
  2. .js → mira el package.json más cercano: con "type": "module", ESM; si no, CommonJS.
{
  "name": "mi-proyecto",
  "type": "module"
}

Para proyectos nuevos, la recomendación es clara: "type": "module" y ESM en todas partes.

Convivir

De ESM a CommonJS funciona sin problemas: puedes importar paquetes CommonJS. Su module.exports llega como exportación por defecto, y Node.js intenta detectar también las exportaciones con nombre:

// main.mjs
import express from "express";          // un paquete CommonJS
import { readFile } from "node:fs/promises";

De CommonJS a ESM fue durante años el lado difícil: require es síncrono y ESM puede no serlo, así que había que usar el import() dinámico. Desde Node 22 (y 20.19) existe require(esm): puedes hacer require de un módulo ESM, siempre que no use await de nivel superior.

// legado.cjs
const { formatear } = require("./util.mjs");   // funciona en Node 22+

Resumen

  • CommonJS es el sistema original de Node.js: require() y module.exports, carga síncrona.
  • ESM es el estándar: import/export, enlaces vivos, modo estricto, también en el navegador.
  • .mjs y .cjs deciden solos; los .js siguen el "type" del package.json.
  • ESM puede importar CommonJS; desde Node 22, CommonJS puede hacer require de ESM sin await de nivel superior.
  • En ESM no existen require, module ni __dirname: usa import e import.meta.

¡A practicar!

Tu progreso se guarda en este navegador.

Autoevaluación: Dos sistemas de módulos

Elige una respuesta en cada pregunta.

  1. ¿Cómo decide Node.js si un archivo .js es ESM o CommonJS?

  2. ¿Qué diferencia clave hay entre lo que exporta CommonJS y lo que exporta ESM?

  3. En un módulo ESM de Node.js, ¿qué reemplaza a __dirname?

  4. ¿Puede un archivo CommonJS cargar un módulo ESM con require() en Node.js moderno?

Ordena la salida: Copias y enlaces vivos

El mismo contador en los dos sistemas. Se ejecuta primero node main.cjs y después node main.mjs. Ordena lo que aparecería en la consola.

// contador.cjslet cuenta = 0;module.exports = { cuenta, sumar: () => ++cuenta }; // main.cjs  (se ejecuta primero)const c = require("./contador.cjs");c.sumar();c.sumar();console.log("cjs:", c.cuenta);console.log("mismo objeto:", require("./contador.cjs") === c); // contador.mjsexport let cuenta = 0;export const sumar = () => ++cuenta; // main.mjs  (se ejecuta después)import { cuenta, sumar } from "./contador.mjs";sumar();sumar();console.log("esm:", cuenta);

Consola, de arriba abajo

  1. esm: 2
  2. cjs: 0
  3. mismo objeto: true

Detective: require en un módulo ESM

Un servidor que funcionaba deja de arrancar después de un cambio en el package.json. Encuentra la línea y elige el arreglo.

Consola

file:///proyecto/servidor.js:1
const fs = require("node:fs");
           ^

ReferenceError: require is not defined in ES module scope, you can use import instead
This file is being treated as an ES module because it has a '.js' file extension and '/proyecto/package.json' contains "type": "module".

Paso 1: toca la línea de código que causa el error.

domina-js · JavaScript en español, gratis y paso a paso.