ECMAScript Modules in Node.js

1. Introduction

ES modules are defined using import and export. For example:

// addTwo.mjs
export function addTwo(num) {
  return num + 2;
}

// app.mjs
import { addTwo } from './addTwo.mjs';
console.log(addTwo(4)); // Prints: 6

2. Enabling ES Modules

• Files with .mjs extension.
• package.json with "type": "module".
• --input-type=module flag.

Conversely, CommonJS can be enforced with .cjs or "type": "commonjs".

3. Import Specifiers

• Relative: ./startup.js, ../config.mjs.
• Bare: some-package, some-package/shuffle.
• Absolute: file:///opt/nodejs/config.js.

Relative and absolute imports require explicit file extensions.

4. URLs

• Modules are resolved and cached as URLs.
• file:, node:, and data: schemes are supported.
• data: imports support JavaScript, JSON, and WASM.

5. Import Attributes

Import attributes allow specifying type information:

import fooData from './foo.json' with { type: 'json' };

The type: 'json' attribute is mandatory for JSON imports.

6. Built-in Modules

Built-in modules provide named exports and a default export:

import { readFile } from 'node:fs';
import EventEmitter from 'node:events';

Named exports can be synchronized using module.syncBuiltinESMExports().

7. Dynamic import()

import() expressions provide asynchronous loading of ES or CommonJS modules.

8. import.meta

• import.meta.url: Absolute file URL of the module.
• import.meta.filename: Full resolved path of the module.
• import.meta.dirname: Directory name of the current module.
• import.meta.main: True if the module is the entry point.

9. Example: import.meta.main

export function foo() { return 'Hello, world'; }

function main() {
  console.log(foo());
}

if (import.meta.main) main();

Conclusion

ECMAScript modules in Node.js provide a modern, standardized way to structure applications. With explicit import/export syntax, support for JSON and WASM, and features like import.meta, ES modules enable clean, interoperable, and future-proof code organization.

1. import.meta.resolve

import.meta.resolve(specifier) returns the absolute URL string for a module specifier relative to the current module. It supports Node.js resolution rules and package exports.

const asset = import.meta.resolve('component-lib/asset.css');
// file:///app/node_modules/component-lib/asset.css

import.meta.resolve('./dep.js');
// file:///app/dep.js

This feature may involve synchronous file system operations and is not available in custom loaders.

2. Interoperability with CommonJS

• import statements can load CommonJS modules.
• The module.exports object is provided as the default export.
• Static analysis attempts to expose named exports for compatibility.

// cjs.cjs
exports.name = 'exported';

// ESM
import { name } from './cjs.cjs';
console.log(name); // 'exported'

3. Differences Between ESM and CommonJS

• No require, exports, or module.exports in ESM.
• __filename and __dirname are replaced by import.meta.filename and import.meta.dirname.
• Addons must be loaded via module.createRequire() or process.dlopen.
• require.main is replaced by import.meta.main.
• ESM uses its own cache, separate from require.cache.

4. JSON Modules

JSON imports require the with { type: 'json' } attribute:

import config from './package.json' with { type: 'json' };

5. WASM Modules

• Source Phase Imports: Import a WebAssembly.Module object for custom instantiation.
• Instance Phase Imports: Import .wasm files as normal modules with exports.

import source libraryModule from './library.wasm';
const instance = await WebAssembly.instantiate(libraryModule, importObject);

6. Top-level await

ESM supports await at the top level:

// a.mjs
export const five = await Promise.resolve(5);

// b.mjs
import { five } from './a.mjs';
console.log(five); // 5

7. Resolution Algorithm

The ESM resolver in Node.js is URL-based and includes:

• Relative and absolute URL resolution.
• No default extensions.
• No folder mains.
• Bare specifier resolution via node_modules.

Conclusion

import.meta.resolve and ESM/CommonJS interoperability in Node.js provide powerful tools for module management. With support for JSON, WASM, and top-level await, developers can build modern, flexible, and efficient applications.