Módulos ES frente a CommonJS en Node.js

Qué es

CommonJS (CJS) es el sistema de módulos original de Node: require() carga de forma sincrónica en tiempo de ejecución, y un módulo exporta lo que sea que asigne a module.exports. Los módulos ES (ESM) son el estándar del lenguaje: import y export son estáticos, se resuelven antes de que se ejecute el cuerpo del módulo, la carga es asíncrona, se permite await de nivel superior, y import.meta lleva metadatos del módulo. Node decide por archivo: .mjs siempre es ESM, .cjs siempre es CJS, y .js sigue el campo "type" del package.json más cercano. Sin un campo "type", la documentación de paquetes llama ambiguo al archivo: las versiones actuales de Node lo ejecutan primero como CommonJS y, si el analizador encuentra sintaxis de módulo ES, lo reevalúan como un módulo ES (detección de sintaxis); las versiones más antiguas simplemente lo tratan como CommonJS. La documentación de ESM enumera lo que falta en ESM (require, module.exports, __filename, __dirname) y sus sustitutos: import.meta.filename, import.meta.dirname, import.meta.resolve() y module.createRequire(). ESM puede importar CommonJS (la importación predeterminada es module.exports), y las versiones actuales de Node pueden hacer require() de un módulo ES siempre que su grafo no contenga await de nivel superior.

Por qué importa

Mezclar ambos sistemas está detrás de los errores de arranque más habituales en los proyectos de Node: «Cannot use import statement outside a module», ERR_REQUIRE_ESM, exports is not defined. Los ejecutores de pruebas, la salida de TypeScript y los empaquetadores tienen cada uno su propia configuración de módulos, y un desajuste falla en tiempo de ejecución en lugar de en tiempo de compilación.

Cómo aplicarlo

• Código nuevo: establecer "type": "module" en package.json y escribir todo en ESM; nombrar .cjs a los pocos archivos que deban permanecer en CommonJS.
• Las importaciones relativas en ESM deben incluir la extensión del archivo (./util.js, ./dir/index.js); el resolutor no la adivina.
• El JSON se importa con un atributo: import cfg from "./cfg.json" with { type: "json" }.
• Bibliotecas que distribuyen ambos formatos: declarar "exports" con las condiciones import y require, y leer antes la documentación de paquetes y su repositorio de ejemplos enlazado sobre paquetes duales; un paquete cargado por ambos puntos de entrada existe dos veces, con estado de módulo separado (el riesgo de paquete dual).
• En los navegadores, los scripts de módulo deben servirse con un tipo MIME de JavaScript como text/javascript; MDN documenta el error de comprobación estricta del tipo MIME para los archivos .mjs servidos de otro modo.

Trampas

Las importaciones circulares se comportan de forma distinta: los enlaces (bindings) de ESM son activos pero pueden estar sin inicializar si se leen demasiado pronto. Un require() de un ESM que usa await de nivel superior lanza ERR_REQUIRE_ASYNC_MODULE; usar import() en su lugar. Un compilador que emite llamadas a require dentro de un paquete "type": "module" produce código que falla al cargarse; mantener alineada la configuración de salida de módulos del compilador con el runtime.