JavaScript
Compara ESM y CommonJS en sintaxis, carga, evaluación e interoperabilidad para entender cómo conviven los dos sistemas de módulos en JavaScript.
es el sistema de módulos estandarizado por ECMAScript. es un sistema histórico de Node.js basado en y .
requiremodule.exports// ESM
import { readFile } from "node:fs/promises";
export function load() {}// CommonJS
const fs = require("node:fs");
module.exports = { load };| Aspecto | ESM | CommonJS |
|---|---|---|
| Sintaxis | import/export | require/module.exports |
| Análisis | Grafo estático | Carga durante ejecución |
| Bindings | Vivos | Valor retornado por require |
| Top-level await | Sí | No como sintaxis propia |
| Navegador | Nativo | No nativo sin herramientas |
Node puede determinar el formato mediante:
.mjs para ESM..cjs para CommonJS..js según el type del package.json más cercano.{
"type": "module"
}Sé explícito. Depender de detección ambigua dificulta herramientas y mantenimiento.
CommonJS ofrece históricamente:
require;
module;
exports;
__filename;
__dirname;No existen con el mismo contrato dentro de ESM. En ESM se usan URLs de módulo y APIs del runtime.
import.meta.url;Importar CommonJS desde ESM puede producir un namespace adaptado, normalmente con un default que representa module.exports.
import legacyPackage from "legacy-package";Named exports detectados desde CommonJS dependen de análisis del runtime y no siempre equivalen a bindings nativos.
Las reglas dependen de la versión de Node y de si el grafo ESM es síncrono. Un módulo con top-level await no puede cargarse como si fuera CommonJS síncrono.
Cuando la compatibilidad importa, revisa la documentación del runtime objetivo.
module.exports = {
createClient,
};exports comienza como referencia a module.exports.
Peligroso:
exports = {
createClient,
};Solo reasigna la variable local y no cambia module.exports.
CommonJS y ESM cachean módulos según sus mecanismos de resolución, pero no deben asumirse idénticos. Mezclar loaders puede crear instancias o formas de acceso diferentes.
Un paquete puede ofrecer entrada ESM y CommonJS mediante exports condicionales.
{
"exports": {
".": {
"import": "./dist/index.js",
"require": "./dist/index.cjs"
}
}
}Esto añade riesgo de dual package hazard: consumidores distintos pueden cargar implementaciones separadas y no compartir estado o identidad.
Para código nuevo multiplataforma, ESM suele ser la opción principal.
CommonJS sigue apareciendo en:
La migración debe revisar resolución, extensiones, globals, tests y tooling.
import {
fileURLToPath,
} from "node:url";
import path from "node:path";
const filename = fileURLToPath(import.meta.url);
const dirname = path.dirname(filename);No copies __dirname como global inexistente dentro de ESM.
¿Por qué exports = { value } no reemplaza la exportación CommonJS?
Porque solo cambia la variable local exports. El valor que require retorna está almacenado en module.exports.
Paquetes, dependencias y package.json explica cómo se describe una unidad distribuible de código.