LogoفارسیFA

ECMAScript Modules in Node.js

ECMAScript modules (ESM) are the official standard for packaging JavaScript code for reuse. They use import and export statements and are fully supported in Node.js, alongside interoperability with CommonJS. Node.js allows developers to explicitly mark files as ES modules using .mjs, the "type": "module" field in package.json, or the --input-type=module flag. ES modules provide modern features such as dynamic imports, import.meta properties, and support for JSON and WASM imports.

import / export.mjs / .cjs / package.json typerelative, bare, and absolute specifiersfile:, node:, data: URLs

~3 min read • Updated Dec 29, 2025

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.


Written & researched by Dr. Shahin Siami

Next Article