.JS File Format – Modules

Import declarations

ImportDeclaration:
    import ImportClause FromClause [WithClause] ;
    import ModuleSpecifier [WithClause] ;
ImportClause:
    ImportedDefaultBinding
    NameSpaceImport
    NamedImports
    ImportedDefaultBinding , NameSpaceImport
    ImportedDefaultBinding , NamedImports
NameSpaceImport:
    * as ImportedBinding
NamedImports:
    { }
    { ImportsList [,] }
ImportSpecifier:
    ImportedBinding
    ModuleExportName as ImportedBinding
FromClause:
    from ModuleSpecifier
ModuleSpecifier:
    StringLiteral

• An import is allowed only at the top level of a module, and is hoisted.
• The specifier must be a string literal, not an expression. Use import() for computed ones.
• The same import in many modules gets one shared instance.

Export declarations

ExportDeclaration:
    export ExportFromClause FromClause [WithClause] ;
    export NamedExports ;
    export VariableStatement
    export Declaration
    export default HoistableDeclaration
    export default ClassDeclaration
    export default [lookahead ∉ { function, async function, class }] AssignmentExpression ;
ExportFromClause:
    *
    * as ModuleExportName
    NamedExports
ExportSpecifier:
    ModuleExportName
    ModuleExportName as ModuleExportName
ModuleExportName:
    IdentifierName
    StringLiteral

• An exported name must be unique in the module, or it is a syntax error.
• export default of an expression has no local name: internally it is the binding *default*.
• If two export * clauses provide the same name, the name is ambiguous. It is not exported, and importing it is an error.

Linking and evaluation

A host loads a module graph in phases before any module runs:

1. Load and parse. Each module is fetched, then parsed, and its imports found.
2. Link. Imports are connected to the exporting bindings, and missing names are errors (a SyntaxError).
3. Evaluate. Modules run once each, children first, in depth-first post-order.

Imports are live bindings: the importer sees the exporter’s variable, and changes show through. Importers cannot assign to them, so x = 1 on an imported x throws a TypeError.

// counter.js
export let count = 0;
export function up() { count++; }

// main.js
import { count, up } from './counter.js';
up();
console.log(count);   // 1

Namespace objects

import * as ns gives a Module Namespace Exotic Object. Its keys are the export names, sorted by code unit. It has no prototype, its Symbol.toStringTag is "Module", it cannot be extended, and all its properties are read-only live views of the bindings.

import * as maths from './maths.js';
Object.keys(maths);    // sorted export names
maths.add(1, 2);
maths.default;         // the default export, if any

Dynamic import

ImportCall:
    import ( AssignmentExpression [, AssignmentExpression] [,] )

import(specifier, options) (ES2020) is an expression that returns a promise for a namespace object. It works in scripts and in modules. The specifier may be computed, and options may hold { with: { type: 'json' } }.

const { default: plugin } = await import(`./plugins/${name}.js`);

Import attributes

WithClause:
    with { }
    with { WithEntries [,] }
WithEntries:
    AttributeKey : StringLiteral
    AttributeKey : StringLiteral , WithEntries

import data from './data.json' with { type: 'json' };
const css = await import('./style.css', { with: { type: 'css' } });

• Import attributes and JSON modules are in ES2025. A JSON module has one export, default.
• A host rejects attribute keys it does not support.
• An earlier draft used the keyword assert, which has been replaced by with.
• In browsers, type: 'css' loads a CSS module script. In Node.js, type: 'json' is required when importing JSON.

import.meta

import.meta (ES2020) is an object created by the host for each module. It is a syntax error in a script. ECMA-262 defines no properties of its own.

Top-level await

// config.js
const res = await fetch('/config.json');
export const config = await res.json();

await at the top level of a module (ES2022) makes the module async. Its importers wait for it, while unrelated sibling modules keep running. A rejected module makes everything depending on it fail. Evaluation stays in order: sibling modules start in source order, and any importer waits until its dependencies are done. It is not allowed in a script, where await is an identifier.

CommonJS and interop

CommonJS is the module system Node.js used before ES modules, and is not part of ECMA-262. Node.js wraps each file in a function, and runs it as a script:

(function(exports, require, module, __filename, __dirname) {
  // the module’s code is here
});

• exports starts out as the same object as module.exports. Assigning to it just rebinds the local variable, so only module.exports = … replaces what is exported.
• Importing CommonJS from an ES module: the default export is module.exports. Node.js also finds named exports by static analysis of the source. That detection misses exports added dynamically, and those are not live bindings.
• Requiring an ES module from CommonJS: require() can load a synchronous ES module, returning its namespace object. It is enabled without a flag in Node.js 22.12, 20.19 and 23.0 and later. If the module or its graph uses top-level await, it throws ERR_REQUIRE_ASYNC_MODULE; use import() for those.
• An ES module can choose the exact value for require() by exporting it under the string name 'module.exports'.
• module.createRequire() builds a require function for use in an ES module.