Home / Backend / CommonJS y ESM en Node.js 26: caché, ciclos y require(esm)
CommonJS y ESM en Node.js 26: caché, ciclos y require(esm)

CommonJS y ESM en Node.js 26: caché, ciclos y require(esm)

19 November 2026 · 23 min de lectura ··

Dos sistemas de módulos conviviendo en Node.js

Durante años, cualquier persona que empezaba con Node.js se topaba con la misma pregunta: por qué un archivo funciona con require y otro exige import. En noviembre de 2026 la situación es mucho más amable que hace unos años, pero sigue habiendo confusión. Node.js 26 acaba de entrar en soporte a largo plazo (LTS), Node.js 24 está en fase de mantenimiento y Node.js 22 sigue recibiendo parches de seguridad hasta abril de 2027. Todas esas líneas conviven en servidores, contenedores y pipelines de integración continua, y por eso conviene entender bien los dos sistemas de módulos que soportan.

CommonJS es el sistema original de Node.js. Se basa en tres piezas: el objeto module, la función require y la propiedad module.exports. ECMAScript Modules, abreviado ESM, es el estándar del lenguaje, se escribe con import y export y funciona igual en el navegador y en el servidor. Durante mucho tiempo ambos mundos estaban separados por una pared: ESM podía importar CommonJS, pero CommonJS no podía cargar ESM de forma síncrona. Esa pared ha caído en las versiones actuales, y eso cambia la forma de publicar librerías y de migrar aplicaciones.

En este artículo recorremos el funcionamiento interno de module y require, las diferentes formas de exportar, cómo se resuelve una ruta, cómo funciona la caché, qué pasa con las dependencias circulares y cuál es el estado actual de require(esm). Cerramos con una guía de errores típicos y su solución. Si quieres una visión complementaria centrada en la importación en general, puedes consultar Todo sobre la importación de módulos en Node.js, y si lo que buscas es un repaso más básico de cómo organizar el código, tienes cómo usar módulos en Node.js.

Los ejemplos de este texto usan un pequeño proyecto ficticio de gestión de inventario, con archivos como precios.js, almacen.js y informe.js. Funcionan en cualquier versión soportada de Node.js, y donde hay diferencias entre versiones se indica de forma explícita.

Qué es realmente un módulo en Node.js

En Node.js cada archivo se trata como un módulo independiente. Lo que declaras dentro de él, ya sean variables, funciones o clases, es privado por defecto y no contamina el ámbito global. Esto no es magia del lenguaje: en el caso de CommonJS, Node.js envuelve el contenido del archivo en una función antes de ejecutarlo. Esa función recibe cinco parámetros: exports, require, module, __filename y __dirname.

Puedes comprobarlo con un archivo mínimo:

// diagnostico.js
console.log(typeof exports);
console.log(typeof require);
console.log(typeof module);
console.log(__filename);
console.log(__dirname);
console.log(arguments.length);
object
function
object
/home/usuario/inventario/diagnostico.js
/home/usuario/inventario
5

El último valor revela el truco: arguments.length solo existe dentro de una función, y aquí vale cinco. Gracias a esa envoltura, una variable como const total = 10 en un archivo jamás choca con otra del mismo nombre en un archivo distinto. También explica por qué return a nivel superior es válido en un archivo CommonJS, algo que sorprende a quienes lo ven por primera vez.

Un detalle importante es que this en el nivel superior de un módulo CommonJS apunta a module.exports, no al objeto global. Es una fuente habitual de confusión cuando se copia código desde el navegador o desde scripts antiguos.

El objeto module y su propiedad exports

El objeto module representa al módulo actual. Si lo imprimes, verás varias propiedades: un identificador, la ruta del archivo, la lista de módulos hijos, las rutas donde Node.js buscará dependencias y, sobre todo, exports. Esa propiedad empieza siendo un objeto vacío y es justo lo que otros archivos recibirán cuando te importen.

// estado.js
console.log(module.id);
console.log(module.filename);
console.log(module.loaded);
console.log(module.exports);
console.log(module.children.length);
.
/home/usuario/inventario/estado.js
false
{}
0

Observa que module.loaded vale false mientras el archivo se está ejecutando. Pasa a true solo cuando termina de cargarse. Este pequeño detalle será clave más adelante, cuando hablemos de ciclos. Además, el identificador del módulo principal es un punto, mientras que en el resto de módulos coincide con la ruta absoluta.

Lo que require devuelve a quien te importa es exactamente el valor de module.exports en el momento en que el archivo termina de ejecutarse. Nada más. Si no exportas nada, quien importe recibirá un objeto vacío.

Formas de poblar module.exports

Hay varias maneras equivalentes de exponer funcionalidad. Elegir una u otra es sobre todo cuestión de estilo y de qué quieres que reciba el consumidor.

La primera consiste en añadir propiedades una a una, con notación de punto o de corchetes:

// precios.js
const IVA = 0.21;

module.exports.conImpuesto = function (base) {
  return base * (1 + IVA);
};

module.exports["sinImpuesto"] = function (total) {
  return total / (1 + IVA);
};

La segunda asigna un objeto literal completo al final del archivo, lo que da una visión clara de la interfaz pública en un solo lugar:

// almacen.js
const existencias = new Map();

function alta(codigo, unidades) {
  existencias.set(codigo, (existencias.get(codigo) ?? 0) + unidades);
}

function consulta(codigo) {
  return existencias.get(codigo) ?? 0;
}

module.exports = { alta, consulta };

La tercera exporta un único valor, como una función o una clase, de modo que el consumidor lo reciba directamente sin tener que desestructurar:

// generarCodigo.js
let contador = 1000;

module.exports = function generarCodigo(prefijo) {
  contador += 1;
  return `${prefijo}-${contador}`;
};

Y el consumidor lo utiliza así:

// informe.js
const { conImpuesto } = require("./precios");
const { alta, consulta } = require("./almacen");
const generarCodigo = require("./generarCodigo");

const codigo = generarCodigo("TORN");
alta(codigo, 40);

console.log(codigo, consulta(codigo));
console.log(conImpuesto(100).toFixed(2));
TORN-1001 40
121.00

Un punto sutil: la clave que exportas no tiene por qué coincidir con el nombre de la variable interna. Puedes escribir module.exports = { precioFinal: calcular } y el consumidor deberá usar precioFinal. Si intenta acceder a una clave que no existe, por ejemplo precios.descuento, no recibirá un error de referencia sino undefined, porque se trata de una simple consulta de propiedad sobre un objeto. Por eso los fallos de nombre suelen aparecer más tarde, cuando intentas invocar ese valor y obtienes un TypeError.

exports frente a module.exports

Dentro de cada módulo existe también la variable exports, que al principio apunta al mismo objeto que module.exports. Es un atajo cómodo, pero genera uno de los errores más clásicos de Node.js.

// atajo_correcto.js
exports.saludo = () => "hola";
// funciona: se añade una propiedad al objeto compartido
// atajo_roto.js
exports = { saludo: () => "hola" };
// no funciona: se reasigna la variable local, no module.exports

En el segundo caso, exports pasa a apuntar a un objeto nuevo, pero require sigue devolviendo lo que cuelga de module.exports, que continúa siendo el objeto vacío original. El consumidor recibirá {} y no se emitirá ningún aviso. La regla práctica es sencilla: si vas a sustituir el valor exportado por completo, usa siempre module.exports =; si solo añades propiedades, cualquiera de las dos formas sirve. Muchas guías de estilo recomiendan usar únicamente module.exports para evitar dudas.

Cómo resuelve Node.js lo que le pasas a require

La función require acepta una cadena y decide qué cargar según su forma. Hay tres grandes casos.

El primero son los módulos nativos, como fs, path o http. Hoy se recomienda escribirlos con el prefijo node:, por ejemplo require("node:fs"). Así queda claro que no se trata de un paquete instalado, y además evita que un paquete de terceros con el mismo nombre pueda suplantarlo.

El segundo son las rutas, que empiezan por ./, ../ o /. Aquí Node.js intenta, por orden, cargar el archivo exacto, añadirle extensiones (.js, .json, .node) y, si es un directorio, buscar su package.json con el campo main o un index.js.

El tercero son los nombres desnudos, como express o zod. Node.js sube por el árbol de directorios buscando carpetas node_modules: primero en la carpeta del archivo actual, luego en la carpeta padre, y así hasta la raíz. En paquetes modernos también interviene el campo exports del package.json, que define con precisión qué subrutas son públicas.

Puedes inspeccionar el resultado sin ejecutar nada:

// donde.js
console.log(require.resolve("./precios"));
console.log(require.resolve("node:path"));
console.log(module.paths.slice(0, 2));
/home/usuario/inventario/precios.js
node:path
[
  '/home/usuario/inventario/node_modules',
  '/home/usuario/node_modules'
]

require.resolve es una herramienta de depuración muy útil: te dice qué archivo concreto se cargaría, o lanza un error si no lo encuentra, sin llegar a ejecutarlo. Cuando un paquete se comporta de forma extraña, es el primer lugar donde mirar.

La caché de require y sus consecuencias

Aquí está uno de los comportamientos más importantes de todo el sistema. La primera vez que cargas un módulo, Node.js lo resuelve, lo lee, lo ejecuta y guarda el resultado en require.cache, indexado por la ruta absoluta del archivo. Las siguientes llamadas a require con el mismo archivo no vuelven a ejecutar el código: devuelven directamente el objeto guardado.

// contador.js
console.log("contador.js se ejecuta");
let veces = 0;

module.exports = {
  incrementar() {
    veces += 1;
    return veces;
  },
};
// prueba_cache.js
const a = require("./contador");
const b = require("./contador");

console.log(a === b);
console.log(a.incrementar());
console.log(b.incrementar());
contador.js se ejecuta
true
1
2

El mensaje aparece una sola vez y ambas variables apuntan al mismo objeto. Esto convierte a los módulos CommonJS en singletons de hecho: un estado compartido, como una conexión a base de datos o una configuración leída del disco, se inicializa una vez y todos los consumidores lo reutilizan. Es cómodo, pero también significa que el estado del módulo persiste durante toda la vida del proceso, algo a tener en cuenta en pruebas automáticas donde necesitas partir de cero.

Existen dos matices relevantes. El primero es que la caché se indexa por ruta resuelta, no por la cadena que escribiste. Si dos paquetes distintos instalan cada uno su copia de la misma librería en carpetas node_modules diferentes, habrá dos instancias independientes, cada una con su propio estado. Esto explica problemas raros como comprobaciones instanceof que fallan entre dos copias de una misma clase.

El segundo es que en sistemas de archivos con distinta capitalización o con enlaces simbólicos, una misma ruta lógica puede acabar con dos entradas. Node.js usa por defecto la ruta real, resolviendo los enlaces, lo que evita la mayoría de los duplicados, aunque algunas herramientas de monorepositorio activan una opción para conservar los enlaces y los reintroducen.

Invalidar la caché a propósito

Puedes borrar una entrada de la caché para forzar una recarga:

// recarga.js
const ruta = require.resolve("./contador");

require("./contador").incrementar();
delete require.cache[ruta];

const nuevo = require("./contador");
console.log(nuevo.incrementar());
contador.js se ejecuta
contador.js se ejecuta
1

Esta técnica se usa en recargadores en caliente y en algunos entornos de pruebas, pero no es una API para producción: los módulos que ya importaron la versión anterior seguirán conservando su referencia al objeto viejo. En código de aplicación es casi siempre preferible diseñar una función que devuelva una instancia nueva en lugar de manipular la caché.

Dependencias circulares en CommonJS

Una dependencia circular aparece cuando el módulo A requiere a B y B requiere a A, directa o indirectamente. Node.js no lo prohíbe, y gracias a la caché no entra en un bucle infinito, pero el resultado puede sorprender.

Cuando A empieza a cargarse, se registra en la caché antes de terminar. Si durante su ejecución carga a B, y B a su vez pide A, recibirá lo que A haya exportado hasta ese momento, es decir, un objeto parcial. Veámoslo con un ejemplo:

// pedidos.js
console.log("pedidos: inicio");
exports.estado = "cargando";

const clientes = require("./clientes");
console.log("pedidos ve clientes.listo =", clientes.listo);

exports.estado = "completo";
console.log("pedidos: fin");
// clientes.js
console.log("clientes: inicio");
const pedidos = require("./pedidos");
console.log("clientes ve pedidos.estado =", pedidos.estado);

exports.listo = true;
console.log("clientes: fin");
pedidos: inicio
clientes: inicio
clientes ve pedidos.estado = cargando
clientes: fin
pedidos ve clientes.listo = true
pedidos: fin

Al ejecutar node pedidos.js, clientes recibe el objeto de pedidos en pleno proceso de construcción, con estado todavía en "cargando". Cuando clientes termina, pedidos continúa con normalidad. Aquí el ciclo funciona porque ambos usan exports.propiedad, de forma que el objeto que ven los demás es el mismo y se va completando.

El problema surge cuando se reasigna module.exports:

// ciclo_roto_a.js
const b = require("./ciclo_roto_b");
module.exports = { nombre: "A", vecino: b.nombre };
// ciclo_roto_b.js
const a = require("./ciclo_roto_a");
module.exports = { nombre: "B", vecino: a.nombre };
{ nombre: 'A', vecino: 'B' }

Si ejecutas ciclo_roto_a.js como entrada, parece funcionar, pero B recibió el objeto vacío original de A, porque A reasignó module.exports después. En B, a.nombre vale undefined, y lo mismo ocurre con cualquier función que B intente llamar de A. Es un fallo silencioso y difícil de rastrear.

Cómo evitar y resolver ciclos

Las soluciones más habituales son estas:

  • Extraer lo compartido a un tercer módulo del que dependan A y B, de modo que el grafo deje de ser circular.
  • Mover el require al interior de la función que lo necesita, de forma que se resuelva en tiempo de ejecución y no al cargar el archivo.
  • Usar siempre exports.nombre = ... en los módulos implicados y no reasignar module.exports.
  • Revisar el diseño: un ciclo suele indicar que dos módulos tienen responsabilidades mezcladas.

Node.js ayuda a detectarlos. En ciertos casos emite una advertencia cuando se accede a una propiedad inexistente de un export parcial por culpa de un ciclo, y herramientas como madge o reglas de ESLint permiten encontrarlos de forma estática antes de que lleguen a producción.

ESM: otra forma de cargar y de entender los módulos

Con ESM las reglas cambian en aspectos importantes. La sintaxis es declarativa:

// precios.mjs
const IVA = 0.21;

export function conImpuesto(base) {
  return base * (1 + IVA);
}

export default function descuento(total, porcentaje) {
  return total * (1 - porcentaje / 100);
}
// informe.mjs
import descuento, { conImpuesto } from "./precios.mjs";
import { readFile } from "node:fs/promises";

console.log(conImpuesto(50));
console.log(descuento(200, 15));

Las diferencias de fondo respecto a CommonJS son varias. Las importaciones se analizan antes de ejecutar el código, por lo que el grafo de dependencias se conoce de antemano. Las rutas relativas deben incluir la extensión completa; no existe la búsqueda automática de .js ni de index.js. No existen __filename ni __dirname, aunque desde las versiones actuales dispones de import.meta.dirname y import.meta.filename. Además, this a nivel superior es undefined y el modo estricto está siempre activo.

Otra diferencia esencial: los exports de ESM son enlaces vivos (live bindings), no copias. Si el módulo exportador cambia el valor de una variable exportada, los importadores ven el cambio. En CommonJS, al desestructurar con const { x } = require(...), obtienes una copia del valor en ese instante.

// vivo.mjs
export let nivel = 1;
export function subir() {
  nivel += 1;
}
// usa_vivo.mjs
import { nivel, subir } from "./vivo.mjs";

console.log(nivel);
subir();
console.log(nivel);
1
2

Con ESM, además, la carga es asíncrona por naturaleza, y eso permite el uso de await a nivel superior, algo imposible en CommonJS. Esa propiedad es precisamente la que hizo difícil durante años cargar un módulo ESM desde require, que es síncrono.

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

Node.js determina el formato de cada archivo según varias reglas, en este orden de prioridad práctico:

  • La extensión .mjs siempre es ESM y .cjs siempre es CommonJS.
  • Para .js, se mira el campo type del package.json más cercano: con "type": "module" es ESM y con "type": "commonjs" o sin el campo, es CommonJS.
  • Para entradas sin extensión o por texto en línea, puede usarse la bandera --input-type.
  • Desde las versiones recientes, si un archivo .js sin campo type contiene sintaxis claramente ESM, Node.js lo detecta y lo ejecuta como módulo, en lugar de fallar con un error de sintaxis.

Un package.json típico para un proyecto moderno se parece a este:

{
  "name": "inventario",
  "version": "1.0.0",
  "type": "module",
  "engines": {
    "node": ">=22"
  },
  "exports": {
    ".": {
      "import": "./src/index.js",
      "require": "./src/index.cjs"
    }
  }
}

Declarar type de forma explícita es una buena práctica incluso si dependes de la detección automática: elimina ambigüedades, acelera el arranque porque Node.js no tiene que analizar el código para decidir, y evita sorpresas con herramientas externas. El campo engines ayuda a dejar claro qué versiones soportas, algo relevante porque las funciones que se describen a continuación dependen de ellas.

Interoperabilidad: de ESM a CommonJS y viceversa

La dirección más sencilla siempre fue importar CommonJS desde ESM. Un módulo ESM puede hacer import de un archivo CommonJS, y lo que recibe como export por defecto es el valor de module.exports. Node.js además intenta detectar de forma estática los nombres exportados para permitir importaciones con nombre, aunque no siempre lo consigue con patrones dinámicos.

// desde_esm.mjs
import legado from "./almacen.js";
import { consulta } from "./almacen.js";

console.log(typeof legado.alta, typeof consulta);

La dirección inversa, cargar ESM desde CommonJS, tenía históricamente una sola opción: la importación dinámica con import(), que devuelve una promesa.

// desde_cjs.js
async function iniciar() {
  const { conImpuesto } = await import("./precios.mjs");
  console.log(conImpuesto(10));
}

iniciar();

Este método sigue siendo válido y es la opción más portátil, pero obliga a convertir en asíncrono el código que lo usa, lo que a veces se propaga por todo el programa. Para scripts pequeños, o para cargar módulos de forma condicional y diferida, es perfectamente adecuado.

require(esm): la novedad que cambia el panorama

Aquí llega el cambio más relevante de los últimos años. Node.js permite ahora llamar a require sobre un módulo ESM, siempre que ese módulo y su árbol de dependencias sean síncronos, es decir, que no usen await a nivel superior. La característica se estabilizó sin necesidad de banderas en las líneas con soporte actuales: llegó a Node.js 22 a partir de la versión 22.12 y a Node.js 20 desde la 20.19, y está disponible por defecto en Node.js 24 y en Node.js 26. Si trabajas con versiones anteriores a esas, sigues necesitando import().

// usa_require_esm.js
const precios = require("./precios.mjs");

console.log(precios.conImpuesto(80));
console.log(typeof precios.default);
96.8
function

El objeto devuelto es el espacio de nombres del módulo, con una propiedad por cada export con nombre y una propiedad default si existe export por defecto. Esto es importante: el export por defecto no se devuelve directamente como el resultado de require, sino que hay que acceder a .default. Para facilitar la convivencia con código que espera module.exports, un módulo ESM puede declarar un export especial con la cadena "module.exports" y así controlar qué recibe quien lo cargue con require:

// biblioteca.mjs
export function sumar(a, b) {
  return a + b;
}

export { sumar as "module.exports" };
// consumidor.js
const sumar = require("./biblioteca.mjs");
console.log(sumar(2, 3));
5

Límites y errores de require(esm)

Si el módulo ESM, o alguna de sus dependencias, usa await a nivel superior, require lanza un error con el código ERR_REQUIRE_ASYNC_MODULE, porque no puede esperar de forma síncrona. En ese caso no queda más remedio que usar import().

Error [ERR_REQUIRE_ASYNC_MODULE]: require() cannot be used on an ESM graph with top-level await.

Para quien publica librerías, el efecto práctico es enorme. Antes había que mantener dos compilaciones, una CommonJS y otra ESM, y acertar con el mapa de exports. Hoy es razonable publicar solo ESM si el código es síncrono en su carga, porque los consumidores CommonJS podrán usarlo con require. Aun así, si tu paquete debe funcionar en entornos antiguos o en empaquetadores con otro comportamiento, mantener la doble publicación sigue siendo lo más seguro.

En cuanto a la caché, los módulos cargados con require(esm) se guardan igualmente y comparten la instancia con quienes los importen mediante import. Esto evita duplicados y mantiene el comportamiento de singleton.

Qué versión de Node.js elegir en 2026

Una decisión práctica es qué versión usar. Con el calendario de lanzamientos de Node.js, las versiones pares pasan a LTS en octubre. Node.js 26 entró en LTS en octubre de 2026, con soporte previsto hasta abril de 2029. Node.js 24 pasó a mantenimiento y Node.js 22 termina su vida útil el 30 de abril de 2027. Antes de elegir, consulta siempre la página oficial de versiones, porque los números de parche cambian con frecuencia.

Para un proyecto nuevo, lo razonable es empezar con la LTS más reciente, fijarla con un archivo .nvmrc o con el campo engines y plantear la actualización con calma. Para un proyecto que ya está en producción con Node.js 22, no hay urgencia técnica, pero conviene planificar el salto antes de abril de 2027.

node --version
nvm install --lts
nvm use --lts
node --version
v26.x.x

Con estas versiones, además, muchas de las razones históricas para recurrir a transpiladores han desaparecido. Si antes usabas herramientas como Babel solo para poder escribir import en Node.js, quizá ya no las necesites. Para casos donde sí puedan hacer falta, como proyectos con sintaxis experimental o con objetivos de navegador antiguos, puedes revisar cómo configurar Babel en Node.js para usar JavaScript moderno en 2026.

Plan práctico para migrar de CommonJS a ESM

Migrar no tiene por qué ser un salto al vacío. Un camino gradual y seguro sigue estos pasos.

  1. Actualiza a una versión LTS actual y ejecuta toda tu suite de pruebas para tener una línea base.
  2. Empieza por las hojas del grafo: los módulos sin dependencias internas. Conviértelos a ESM, ya sea renombrando a .mjs o cambiando el type del paquete.
  3. Sustituye require("./x") por import con extensión completa, y module.exports por export.
  4. Reemplaza __dirname y __filename por import.meta.dirname e import.meta.filename.
  5. Convierte las lecturas de JSON a importaciones con atributos de importación, o léelas con fs.
  6. Ajusta la configuración de pruebas, de linter y de empaquetado, que son los puntos donde más fricción aparece.
  7. Elimina "type" ambiguo y deja "type": "module" explícito cuando la mayoría del código ya sea ESM.

Un ejemplo de la conversión de JSON, que en ESM requiere una declaración explícita del tipo:

// config.mjs
import ajustes from "./ajustes.json" with { type: "json" };

console.log(ajustes.moneda);

Y la versión equivalente en CommonJS, que sigue funcionando sin cambios:

// config.js
const ajustes = require("./ajustes.json");
console.log(ajustes.moneda);

Durante la transición puedes mezclar ambos formatos gracias a require(esm) y a la importación de CommonJS desde ESM. Eso permite migrar por partes y desplegar con frecuencia, en lugar de congelar el proyecto durante semanas.

Solución de errores frecuentes

Muchos de los problemas del día a día con módulos en Node.js se repiten una y otra vez. Estos son los más comunes, con su causa y su arreglo.

Error Cannot find module

Error: Cannot find module './precio'
Require stack:
- /home/usuario/inventario/informe.js

El mensaje indica que ninguna de las rutas probadas existe. Revisa mayúsculas y minúsculas, que importan en Linux aunque no en algunos sistemas de archivos de escritorio; comprueba la extensión y que el paquete esté instalado con npm ls nombre. La lista Require stack te muestra quién hizo la petición, y require.resolve te ayuda a depurar la resolución.

Error require is not defined en ESM

ReferenceError: require is not defined in ES module scope, you can use import instead

Estás en un archivo ESM, ya sea por .mjs o por "type": "module", y has usado require. Dos salidas: cambiar a import, o crear tu propia función con createRequire:

// puente.mjs
import { createRequire } from "node:module";

const require = createRequire(import.meta.url);
const legado = require("./almacen.js");

console.log(legado.consulta("TORN-1001"));

Error al usar import fuera de un módulo

SyntaxError: Cannot use import statement outside a module

El caso inverso: usas import en un archivo que Node.js trata como CommonJS. Añade "type": "module" al package.json, renombra el archivo a .mjs o, si el código es CommonJS de verdad, vuelve a require. En las versiones actuales la detección automática de sintaxis suele resolverlo por sí sola, pero declarar el tipo evita depender de ella.

Errores ERR_REQUIRE_ESM y ERR_REQUIRE_ASYNC_MODULE

El primero aparecía en versiones antiguas cada vez que se intentaba cargar un ESM con require. En versiones con require(esm) estable ya no debería verse, salvo que estés en una versión anterior a la 20.19 o 22.12. La solución es actualizar o usar import(). El segundo, como vimos, indica que el grafo ESM contiene await a nivel superior: usa import() o elimina esa espera del módulo.

Error ERR_MODULE_NOT_FOUND con rutas relativas

Error [ERR_MODULE_NOT_FOUND]: Cannot find module '/home/usuario/inventario/precios' imported from /home/usuario/inventario/informe.mjs

En ESM, la resolución no añade extensiones. Escribe ./precios.mjs o ./precios.js completo. Es una de las causas más frecuentes de fallos tras una migración, y se detecta de inmediato al ejecutar.

Error ERR_PACKAGE_PATH_NOT_EXPORTED

Error [ERR_PACKAGE_PATH_NOT_EXPORTED]: Package subpath './interno' is not defined by "exports" in /home/usuario/inventario/node_modules/libreria/package.json

El paquete restringe sus rutas públicas con el campo exports, y estás intentando acceder a un archivo interno. No intentes saltarte la restricción: usa la API pública documentada o abre una incidencia con el mantenedor.

Exports vacíos tras un ciclo

Si un valor importado aparece como undefined o como objeto vacío sin motivo aparente, sospecha de una dependencia circular con reasignación de module.exports. Añade un console.log al inicio y al final de cada archivo implicado para ver el orden de ejecución, o aplica alguna de las soluciones descritas antes.

Dos instancias de un mismo paquete

Si un instanceof falla o el estado parece duplicado, ejecuta npm ls nombre para ver si hay varias versiones instaladas. Unificarlas con npm dedupe o con la sección overrides del package.json suele resolverlo.

Buenas prácticas para código de módulos mantenible

Más allá de los errores, hay hábitos que ahorran problemas a largo plazo.

Define una interfaz pública pequeña. Exporta solo lo que otras partes del programa necesitan, y mantén el resto privado dentro del módulo. Esto facilita los cambios internos sin romper a los consumidores.

Evita el estado global compartido siempre que puedas. La caché convierte los módulos en singletons, lo que está bien para configuración o conexiones, pero resulta peligroso para datos mutables que cambian durante la ejecución. Si necesitas varias instancias, exporta una función fábrica.

// colaDeTrabajo.js
function crearCola() {
  const elementos = [];
  return {
    agregar: (x) => elementos.push(x),
    siguiente: () => elementos.shift(),
    tamano: () => elementos.length,
  };
}

module.exports = { crearCola };

Prefiere el prefijo node: para los módulos nativos, mantén los require o import en la parte superior del archivo salvo cuando haya un motivo claro para diferirlos, y usa nombres de archivo coherentes. Considera la carga diferida con import() para dependencias pesadas que solo se usan en rutas poco frecuentes, como la generación de informes en PDF, de modo que el arranque de la aplicación sea más rápido.

Configura el linter para detectar ciclos y rutas sin extensión, y añade una prueba de humo que importe el punto de entrada de tu paquete tanto con import como con require. Si publicas una librería, esa prueba es la mejor defensa contra un mapa de exports mal escrito.

Rendimiento y diagnóstico de la carga de módulos

La carga de módulos tiene un coste. Cada require a una ruta nueva implica resolver, leer del disco, compilar y ejecutar. En aplicaciones con miles de módulos, como las que usan muchos paquetes de terceros, el tiempo de arranque puede notarse, sobre todo en funciones serverless y en herramientas de línea de comandos.

Algunas técnicas para medirlo y reducirlo:

  • Ejecuta tu aplicación con node --cpu-prof para generar un perfil y localizar los módulos que más tardan al cargarse.
  • Usa la carga diferida para dependencias que no se necesitan al inicio.
  • Aprovecha la caché de compilación de módulos que ofrece Node.js en versiones recientes mediante module.enableCompileCache(), que guarda el código compilado en disco y acelera arranques posteriores.
  • Reduce el número de dependencias y revisa las que arrastran árboles enormes.
// arranque.js
const { enableCompileCache } = require("node:module");

enableCompileCache();

const inicio = performance.now();
require("./informe");
console.log(`carga en ${(performance.now() - inicio).toFixed(1)} ms`);
carga en 12.4 ms

Esos números variarán según el equipo, pero lo importante es medir antes y después de cada cambio, en lugar de optimizar a ciegas. Para depurar el orden de carga, también puedes inspeccionar require.cache o Object.keys(require.cache) y comprobar qué módulos están realmente cargados en un momento dado.

Conclusiones

CommonJS y ESM ya no son dos mundos enfrentados en Node.js. Con las líneas LTS actuales, la diferencia se reduce a una cuestión de diseño: CommonJS sigue siendo sencillo, con su envoltura de función, su objeto module y su caché indexada por ruta; ESM ofrece análisis estático, enlaces vivos, await a nivel superior y una sintaxis estándar compartida con el navegador.

Tres ideas resumen lo más importante. Primero, require devuelve siempre lo que hay en module.exports al terminar la ejecución del archivo, y la caché garantiza que esto ocurra una sola vez, lo que explica tanto los singletons como los ciclos con exports parciales. Segundo, exports es solo un atajo: reasignarlo no cambia lo que se exporta, y reasignar module.exports en un ciclo deja a los demás con un objeto vacío. Tercero, require(esm) permite cargar módulos ESM síncronos desde CommonJS en Node.js 20.19 o posterior, 22.12 o posterior, y en las versiones 24 y 26, por lo que la migración gradual es posible y la publicación de paquetes solo ESM es una opción realista.

Para tu próximo proyecto, empieza con la LTS más reciente, declara el campo type en el package.json, usa el prefijo node: para los módulos nativos y escribe una prueba de humo que cargue tu código de ambos modos. Cuando aparezca un error, lee su código y su pila: casi siempre indica con precisión qué formato esperaba Node.js y cuál recibió.