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:
.mjs→ siempre ESM..cjs→ siempre CommonJS..js→ mira elpackage.jsonmá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()ymodule.exports, carga síncrona. - ESM es el estándar:
import/export, enlaces vivos, modo estricto, también en el navegador. .mjsy.cjsdeciden solos; los.jssiguen el"type"delpackage.json.- ESM puede importar CommonJS; desde Node 22, CommonJS puede hacer
requirede ESM sinawaitde nivel superior. - En ESM no existen
require,moduleni__dirname: usaimporteimport.meta.
¡A practicar!
Tu progreso se guarda en este navegador.
Autoevaluación: Dos sistemas de módulos
Resuelto
Elige una respuesta en cada pregunta.
¿Cómo decide Node.js si un archivo
.jses ESM o CommonJS?¿Qué diferencia clave hay entre lo que exporta CommonJS y lo que exporta ESM?
En un módulo ESM de Node.js, ¿qué reemplaza a
__dirname?¿Puede un archivo CommonJS cargar un módulo ESM con
require()en Node.js moderno?
Ordena la salida: Copias y enlaces vivos
Resuelto
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.
1// contador.cjs2let cuenta = 0;3module.exports = { cuenta, sumar: () => ++cuenta };4 5// main.cjs (se ejecuta primero)6const c = require("./contador.cjs");7c.sumar();8c.sumar();9console.log("cjs:", c.cuenta);10console.log("mismo objeto:", require("./contador.cjs") === c);11 12// contador.mjs13export let cuenta = 0;14export const sumar = () => ++cuenta;15 16// main.mjs (se ejecuta después)17import { cuenta, sumar } from "./contador.mjs";18sumar();19sumar();20console.log("esm:", cuenta);Consola, de arriba abajo
- esm: 2
- cjs: 0
- mismo objeto: true
En CommonJS, module.exports guardó una copia del valor de cuenta en ese momento (0); la variable interna sí sube a 2. En ESM, cuenta es un enlace vivo: ves el valor actual. En los dos sistemas, un módulo se carga una sola vez.
Detective: require en un módulo ESM
Resuelto
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.
Paso 2: ¿cómo lo arreglas?