Docs
README
22.4 ES Modules Internals
Understanding how ES Modules work internally helps you write better module code, avoid circular dependency issues, and optimize load performance.
Table of Contents
- •Module System Overview
- •Module Loading Phases
- •Module Records and Environments
- •Circular Dependencies
- •Dynamic Imports
- •Module Caching
- •Top-Level Await
- •CommonJS vs ES Modules
- •All JavaScript Module Systems
Module System Overview
ES Modules are JavaScript's native module system, designed for static analysis and optimization.
┌─────────────────────────────────────────────────────────────────────┐
│ ES MODULES OVERVIEW │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ KEY CHARACTERISTICS: │
│ │
│ 1. STATIC STRUCTURE │
│ • Imports/exports determined at compile time │
│ • Enables tree-shaking and dead code elimination │
│ • Cannot conditionally import (at top level) │
│ │
│ 2. LIVE BINDINGS │
│ • Imports are references, not copies │
│ • Changes in exporter reflect in importer │
│ │
│ 3. SINGLETON MODULES │
│ • Each module executed only once │
│ • Cached for all subsequent imports │
│ │
│ 4. STRICT MODE BY DEFAULT │
│ • All ES modules run in strict mode │
│ • No need for 'use strict' │
│ │
│ 5. ASYNCHRONOUS LOADING │
│ • Modules can be loaded in parallel │
│ • Execution happens after all dependencies ready │
│ │
└─────────────────────────────────────────────────────────────────────┘
Static vs Dynamic
// ✅ STATIC - Analyzed at compile time
import { foo } from './module.js';
export const bar = 42;
// ❌ NOT STATIC - These are errors at top level
// if (condition) {
// import { foo } from './module.js'; // Error!
// }
// ✅ DYNAMIC - Use dynamic import for runtime decisions
if (condition) {
const { foo } = await import('./module.js'); // OK!
}
Module Loading Phases
ES Module loading happens in three distinct phases.
┌─────────────────────────────────────────────────────────────────────┐
│ MODULE LOADING PHASES │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ PHASE 1: CONSTRUCTION (Parsing) │
│ ──────────────────────────────── │
│ • Fetch module source code │
│ • Parse the source code │
│ • Find import/export statements │
│ • Create Module Record (metadata) │
│ • Build dependency graph │
│ │
│ ┌─────────┐ fetch ┌─────────┐ parse │
│ │ URL │ ───────────→ │ Source │ ───────────→ Module │
│ └─────────┘ └─────────┘ Record │
│ │
│ PHASE 2: INSTANTIATION (Linking) │
│ ─────────────────────────────── │
│ • Allocate memory for all exports │
│ • Link imports to exports (live bindings) │
│ • NO CODE EXECUTED YET │
│ │
│ Module A ─────────── exports ──────────→ binding │
│ ↑ │ │
│ └──────────── imports ─────────────────┘ │
│ │
│ PHASE 3: EVALUATION (Execution) │
│ ───────────────────────────────── │
│ • Execute module code (top-level) │
│ • Fill export bindings with values │
│ • Depth-first, post-order execution │
│ │
│ Dependency tree: Execution order: │
│ A C (first) │
│ / \ D (second) │
│ B C B (third) │
│ | A (last) │
│ D │
│ │
└─────────────────────────────────────────────────────────────────────┘
Phase Details
// main.js
import { value, increment } from './counter.js';
console.log(value); // What happens here?
increment();
console.log(value); // And here?
// counter.js
export let value = 0;
export function increment() {
value++;
}
PHASE 1: CONSTRUCTION
────────────────────
1. Parse main.js → finds import from './counter.js'
2. Fetch and parse counter.js
3. Build Module Records for both
PHASE 2: INSTANTIATION
─────────────────────
1. Allocate memory for counter.js exports (value, increment)
2. Link main.js imports to counter.js exports
3. Both modules ready, no code run yet
PHASE 3: EVALUATION
──────────────────
1. Execute counter.js first (dependency)
- value = 0
- increment function created
2. Execute main.js
- console.log(value) → 0
- increment() → value becomes 1
- console.log(value) → 1 (live binding!)
Module Records and Environments
The JavaScript engine creates internal structures to manage modules.
┌─────────────────────────────────────────────────────────────────────┐
│ MODULE RECORD │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ [[Realm]] The realm this module belongs to │
│ [[Environment]] Module's lexical environment │
│ [[Namespace]] Module namespace object │
│ [[Status]] unlinked | linking | linked | │
│ evaluating | evaluated | error │
│ [[RequestedModules]] List of module specifiers │
│ [[ImportEntries]] List of import entries │
│ [[LocalExportEntries]] List of local export entries │
│ [[StarExportEntries]] Re-exports with * │
│ │
│ Example for: │
│ ──────────── │
│ // module.js │
│ import { x } from './dep.js'; │
│ export const y = x + 1; │
│ export function double(n) { return n * 2; } │
│ │
│ ImportEntries: [{ │
│ ModuleRequest: './dep.js', │
│ ImportName: 'x', │
│ LocalName: 'x' │
│ }] │
│ │
│ LocalExportEntries: [ │
│ { LocalName: 'y', ExportName: 'y' }, │
│ { LocalName: 'double', ExportName: 'double' } │
│ ] │
│ │
└─────────────────────────────────────────────────────────────────────┘
Module Namespace Object
// module.js
export const a = 1;
export const b = 2;
export function c() {
return 3;
}
// main.js
import * as mod from './module.js';
console.log(mod);
// Module Namespace Object:
// {
// a: 1,
// b: 2,
// c: [Function: c],
// [Symbol.toStringTag]: 'Module'
// }
console.log(Object.keys(mod)); // ['a', 'b', 'c']
console.log(Object.isFrozen(mod)); // true (in some environments)
Circular Dependencies
ES Modules handle circular dependencies, but understanding how is crucial.
┌─────────────────────────────────────────────────────────────────────┐
│ CIRCULAR DEPENDENCIES │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ The Problem: │
│ │
│ a.js ──imports──→ b.js │
│ ↑ │ │
│ └────imports───────┘ │
│ │
│ How ES Modules handle it: │
│ │
│ 1. Start evaluating a.js │
│ 2. Hit import from b.js │
│ 3. Pause a.js, start evaluating b.js │
│ 4. b.js tries to import from a.js │
│ 5. a.js already started → use CURRENT state │
│ (even though a.js hasn't finished!) │
│ 6. Finish b.js evaluation │
│ 7. Continue a.js evaluation │
│ │
└─────────────────────────────────────────────────────────────────────┘
Circular Dependency Example
// a.js
import { b } from './b.js';
console.log('a.js: b =', b);
export let a = 'a after';
console.log('a.js: a =', a);
// b.js
import { a } from './a.js';
console.log('b.js: a =', a); // undefined! a.js not finished yet
export let b = 'b after';
console.log('b.js: b =', b);
Execution trace when running a.js:
1. Start a.js
2. Hit "import { b } from './b.js'"
3. Pause a.js (a is allocated but NOT initialized)
4. Start b.js
5. b.js: "import { a } from './a.js'" → a.js already started
6. b.js: console.log('b.js: a =', a) → "a" is UNDEFINED
7. b.js: export b = 'b after'
8. b.js: console.log('b.js: b =', b) → "b after"
9. b.js DONE
10. Resume a.js
11. a.js: console.log('a.js: b =', b) → "b after"
12. a.js: export a = 'a after'
13. a.js: console.log('a.js: a =', a) → "a after"
Output:
b.js: a = undefined
b.js: b = b after
a.js: b = b after
a.js: a = a after
Avoiding Circular Dependency Issues
// ❌ BAD: Accessing export before initialization
// a.js
import { b, getB } from './b.js';
export const a = b + 1; // b might be undefined!
// ✅ GOOD: Use functions that are called later
// a.js
import { getB } from './b.js';
export const a = 'a';
export function getA() {
return a;
}
export function init() {
console.log('b is:', getB()); // Called after both modules loaded
}
// b.js
import { getA } from './a.js';
export const b = 'b';
export function getB() {
return b;
}
export function init() {
console.log('a is:', getA());
}
Dynamic Imports
Dynamic imports allow loading modules at runtime.
┌─────────────────────────────────────────────────────────────────────┐
│ DYNAMIC IMPORTS │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ SYNTAX: │
│ │
│ const module = await import('./module.js'); │
│ │ │
│ └── Returns Promise<ModuleNamespace> │
│ │
│ USE CASES: │
│ │
│ 1. Code Splitting │
│ const { heavyFunction } = await import('./heavy.js'); │
│ │
│ 2. Conditional Loading │
│ if (needsFeature) { │
│ const { feature } = await import('./feature.js'); │
│ } │
│ │
│ 3. Computed Module Paths │
│ const lang = 'en'; │
│ const i18n = await import(`./locales/${lang}.js`); │
│ │
│ 4. Lazy Loading │
│ button.onclick = async () => { │
│ const { handleClick } = await import('./handler.js'); │
│ handleClick(); │
│ }; │
│ │
└─────────────────────────────────────────────────────────────────────┘
Dynamic Import Patterns
// Pattern 1: Lazy Loading Components
async function loadComponent(name) {
const components = {
header: () => import('./components/header.js'),
footer: () => import('./components/footer.js'),
sidebar: () => import('./components/sidebar.js'),
};
return await components[name]?.();
}
// Pattern 2: Feature Detection
async function loadPolyfill() {
if (!('IntersectionObserver' in window)) {
await import('./polyfills/intersection-observer.js');
}
}
// Pattern 3: Parallel Loading
async function loadAllFeatures() {
const [featureA, featureB, featureC] = await Promise.all([
import('./features/a.js'),
import('./features/b.js'),
import('./features/c.js'),
]);
return { featureA, featureB, featureC };
}
// Pattern 4: Fallback Loading
async function loadWithFallback() {
try {
return await import('./feature-modern.js');
} catch {
return await import('./feature-legacy.js');
}
}
Module Caching
Modules are cached after first load—understanding this is important.
┌─────────────────────────────────────────────────────────────────────┐
│ MODULE CACHE │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ Module Map (Browser/Runtime maintains this): │
│ │
│ ┌────────────────────────────────────────────────────────────┐ │
│ │ URL / Specifier │ Module Record │ │
│ ├────────────────────────────────────────────────────────────┤ │
│ │ './counter.js' │ { exports: { count, inc } } │ │
│ │ './utils.js' │ { exports: { helper } } │ │
│ │ 'lodash' │ { exports: { ... } } │ │
│ └────────────────────────────────────────────────────────────┘ │
│ │
│ First import('./counter.js'): │
│ 1. Check cache → Not found │
│ 2. Fetch, parse, instantiate, evaluate │
│ 3. Store in cache │
│ │
│ Second import('./counter.js'): │
│ 1. Check cache → FOUND │
│ 2. Return cached module namespace │
│ 3. NO re-execution │
│ │
│ Implications: │
│ • Module code runs ONCE │
│ • Module state is SHARED │
│ • Same object/function references across all imports │
│ │
└─────────────────────────────────────────────────────────────────────┘
Singleton Pattern via Modules
// counter.js - This is a singleton!
let count = 0;
export function getCount() {
return count;
}
export function increment() {
count++;
}
// fileA.js
import { getCount, increment } from './counter.js';
increment();
console.log(getCount()); // 1
// fileB.js
import { getCount, increment } from './counter.js';
// Same module instance as fileA.js!
console.log(getCount()); // 1 (not 0!)
increment();
console.log(getCount()); // 2
Cache Busting (for Testing/Development)
// Adding a query string creates a "new" module
const counter1 = await import('./counter.js?v=1');
const counter2 = await import('./counter.js?v=2');
// counter1 and counter2 are DIFFERENT instances!
// Note: This is a workaround, not standard behavior
Top-Level Await
ES2022 allows await at the module's top level.
┌─────────────────────────────────────────────────────────────────────┐
│ TOP-LEVEL AWAIT │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ Before (ES2015): │
│ ──────────────── │
│ // config.js │
│ export let config; │
│ │
│ (async () => { │
│ config = await loadConfig(); │
│ })(); │
│ │
│ // Problem: config might be undefined when imported! │
│ │
│ With Top-Level Await (ES2022): │
│ ───────────────────────────── │
│ // config.js │
│ export const config = await loadConfig(); │
│ │
│ // Guaranteed: config is ready when module finishes loading │
│ │
│ Execution Order with TLA: │
│ │
│ main.js │
│ │ │
│ import │
│ │ │
│ ▼ │
│ config.js ──── await loadConfig() ──── │
│ │ │ │
│ │ │ (async operation) │
│ │ │ │
│ ▼ ◄─────────────────────────────┘ │
│ continue main.js │
│ │
│ The importing module WAITS for the async module to complete! │
│ │
└─────────────────────────────────────────────────────────────────────┘
Top-Level Await Examples
// database.js
// Module evaluation waits for connection
const connection = await connectToDatabase();
export { connection };
export async function query(sql) {
return connection.query(sql);
}
// app.js
import { connection, query } from './database.js';
// Connection is guaranteed to be established here
console.log('Connected:', connection.isConnected);
const users = await query('SELECT * FROM users');
TLA Considerations
// ⚠️ TLA can block loading of dependent modules
// config.js
export const config = await fetch('/api/config').then((r) => r.json());
// ↑ This blocks ALL modules that import config.js
// ✅ Better: Use TLA sparingly
// Consider if async initialization is really needed at import time
// Sometimes lazy initialization is better
// Alternative: Lazy initialization
let _config = null;
export async function getConfig() {
if (!_config) {
_config = await fetch('/api/config').then((r) => r.json());
}
return _config;
}
CommonJS vs ES Modules
Understanding the differences helps when working with both systems.
┌─────────────────────────────────────────────────────────────────────┐
│ CJS vs ESM COMPARISON │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ CommonJS ES Modules │
│ ───────────────────────────────────────────────────────────────── │
│ Syntax require() import/export │
│ module.exports export default/named │
│ │
│ Loading Synchronous Asynchronous │
│ (blocking) (non-blocking) │
│ │
│ Resolution Runtime Static (compile time) │
│ Dynamic Known before execution │
│ │
│ Bindings Value copy Live bindings │
│ (snapshot) (reference) │
│ │
│ Evaluation Immediate Deferred │
│ when required after all parsing │
│ │
│ Top-level Sync only Sync + Async (TLA) │
│ │
│ this value module object undefined │
│ │
│ Tree-shaking Not possible Possible │
│ (dynamic) (static analysis) │
│ │
└─────────────────────────────────────────────────────────────────────┘
Live Bindings vs Value Copy
// === CommonJS (Value Copy) ===
// counter.cjs
let count = 0;
module.exports = {
count, // Copies current value
increment: () => count++,
};
// main.cjs
const counter = require('./counter.cjs');
console.log(counter.count); // 0
counter.increment();
console.log(counter.count); // Still 0! (value was copied)
// === ES Modules (Live Binding) ===
// counter.mjs
export let count = 0;
export function increment() {
count++;
}
// main.mjs
import { count, increment } from './counter.mjs';
console.log(count); // 0
increment();
console.log(count); // 1 (live binding - sees updated value)
Interoperability
// ESM importing CJS (usually works)
import lodash from 'lodash'; // CJS module
import { map } from 'lodash'; // May not work for named exports
// CJS importing ESM (requires dynamic import)
// const esm = require('./esm-module.mjs'); // ❌ Error!
const esm = await import('./esm-module.mjs'); // ✅ Works
// Package.json configuration
{
"type": "module", // Treat .js as ESM
"exports": {
"import": "./esm/index.js",
"require": "./cjs/index.cjs"
}
}
All JavaScript Module Systems
A comprehensive overview of all module systems in JavaScript history.
┌─────────────────────────────────────────────────────────────────────┐
│ JAVASCRIPT MODULE SYSTEMS TIMELINE │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ 1999 ┌─────────────────────────────────────────────────────┐ │
│ │ IIFE Module Pattern (Pre-modules) │ │
│ │ First attempt at encapsulation │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
│ 2009 ┌─────────────────────────────────────────────────────┐ │
│ │ CommonJS (CJS) │ │
│ │ Node.js server-side modules │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
│ 2011 ┌─────────────────────────────────────────────────────┐ │
│ │ AMD (Asynchronous Module Definition) │ │
│ │ Browser async loading (RequireJS) │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
│ 2012 ┌─────────────────────────────────────────────────────┐ │
│ │ UMD (Universal Module Definition) │ │
│ │ Works everywhere (CJS + AMD + Global) │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
│ 2015 ┌─────────────────────────────────────────────────────┐ │
│ │ ES6 Modules (ESM) │ │
│ │ Native JavaScript modules │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
│ 2016+ ┌─────────────────────────────────────────────────────┐ │
│ │ Bundler Modules (Webpack/Rollup/Vite) │ │
│ │ Build-time module resolution │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────┘
1. IIFE Module Pattern (Old Module Pattern)
The original way to create private scope in JavaScript.
// IIFE (Immediately Invoked Function Expression) Module Pattern
const MyModule = (function () {
// Private variables
let privateVar = 0;
const privateConst = 'secret';
// Private function
function privateFunction() {
return privateVar * 2;
}
// Public API (Revealing Module Pattern)
return {
increment: function () {
privateVar++;
},
getCount: function () {
return privateVar;
},
getDouble: function () {
return privateFunction();
},
};
})();
// Usage
MyModule.increment();
console.log(MyModule.getCount()); // 1
console.log(MyModule.privateVar); // undefined (private!)
┌─────────────────────────────────────────────────────────────────────┐
│ IIFE MODULE PATTERN │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ PROS: │
│ ✅ No dependencies or build tools needed │
│ ✅ Works in all browsers │
│ ✅ Creates true private scope │
│ ✅ Immediately executable │
│ │
│ CONS: │
│ ❌ No dependency management │
│ ❌ Relies on script order in HTML │
│ ❌ No async loading │
│ ❌ Global namespace pollution (module name) │
│ ❌ Outdated for modern development │
│ │
│ USE CASE: Legacy code, quick scripts, learning closures │
│ │
└─────────────────────────────────────────────────────────────────────┘
2. CommonJS (CJS)
The module system created for Node.js.
// math.js (CommonJS module)
const PI = 3.14159;
function add(a, b) {
return a + b;
}
function multiply(a, b) {
return a * b;
}
// Export multiple items
module.exports = {
PI,
add,
multiply,
};
// Or export individually
// exports.add = add;
// exports.PI = PI;
// main.js (CommonJS consumer)
const math = require('./math');
console.log(math.add(2, 3)); // 5
console.log(math.PI); // 3.14159
// Destructuring import
const { add, multiply } = require('./math');
console.log(multiply(4, 5)); // 20
// Conditional/dynamic require
if (needsMath) {
const dynamicMath = require('./math');
}
┌─────────────────────────────────────────────────────────────────────┐
│ COMMONJS │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ SYNTAX: │
│ require('./module') // Import │
│ module.exports = { ... } // Export object │
│ exports.name = value // Export individual │
│ │
│ CHARACTERISTICS: │
│ • Synchronous loading (blocking) │
│ • Runtime module resolution │
│ • Exports are value COPIES (not live bindings) │
│ • Dynamic imports allowed anywhere │
│ • Circular dependencies: partial exports │
│ │
│ PROS: │
│ ✅ Simple syntax │
│ ✅ Huge NPM ecosystem │
│ ✅ Dynamic requires possible │
│ ✅ Well-understood in Node.js │
│ │
│ CONS: │
│ ❌ Synchronous (bad for browsers) │
│ ❌ No static analysis (no tree-shaking) │
│ ❌ Not native to browsers │
│ ❌ Being phased out for ESM in Node.js │
│ │
│ FILE EXTENSIONS: .js (with type: "commonjs") or .cjs │
│ │
└─────────────────────────────────────────────────────────────────────┘
3. AMD (Asynchronous Module Definition)
Created for browsers to load modules asynchronously.
// math.js (AMD module)
define('math', [], function () {
const PI = 3.14159;
function add(a, b) {
return a + b;
}
function multiply(a, b) {
return a * b;
}
// Return public API
return {
PI: PI,
add: add,
multiply: multiply,
};
});
// main.js (AMD consumer)
define(['math', 'utils'], function (math, utils) {
// Dependencies are injected as arguments
console.log(math.add(2, 3));
console.log(utils.format('Hello'));
});
// Or using require
require(['math'], function (math) {
console.log(math.PI);
});
┌─────────────────────────────────────────────────────────────────────┐
│ AMD │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ SYNTAX: │
│ define(id?, deps?, factory) // Define module │
│ require(deps, callback) // Load modules │
│ │
│ IMPLEMENTATIONS: │
│ • RequireJS (most popular) │
│ • curl.js │
│ • Dojo Toolkit │
│ │
│ CHARACTERISTICS: │
│ • Asynchronous loading │
│ • Browser-first design │
│ • Callback-based API │
│ • Explicit dependency declaration │
│ │
│ PROS: │
│ ✅ Async loading (non-blocking) │
│ ✅ Works in browsers without build step │
│ ✅ Parallel loading of dependencies │
│ ✅ Good for large applications │
│ │
│ CONS: │
│ ❌ Verbose syntax │
│ ❌ Requires RequireJS library │
│ ❌ Mostly obsolete (replaced by ESM + bundlers) │
│ ❌ Complex configuration │
│ │
│ STATUS: Largely obsolete, replaced by ES Modules │
│ │
└─────────────────────────────────────────────────────────────────────┘
4. UMD (Universal Module Definition)
Works in CommonJS, AMD, and browser globals.
// math.js (UMD module)
(function (root, factory) {
if (typeof define === 'function' && define.amd) {
// AMD
define(['exports'], factory);
} else if (
typeof exports === 'object' &&
typeof exports.nodeName !== 'string'
) {
// CommonJS
factory(exports);
} else {
// Browser globals
factory((root.math = {}));
}
})(typeof self !== 'undefined' ? self : this, function (exports) {
// Module code here
exports.PI = 3.14159;
exports.add = function (a, b) {
return a + b;
};
exports.multiply = function (a, b) {
return a * b;
};
});
┌─────────────────────────────────────────────────────────────────────┐
│ UMD │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ PURPOSE: Universal compatibility wrapper │
│ │
│ WORKS IN: │
│ ✓ Node.js (CommonJS) │
│ ✓ RequireJS (AMD) │
│ ✓ Browser script tags (global) │
│ │
│ DETECTION ORDER: │
│ 1. Check for AMD (define.amd) │
│ 2. Check for CommonJS (exports object) │
│ 3. Fall back to browser global │
│ │
│ PROS: │
│ ✅ Maximum compatibility │
│ ✅ Single file works everywhere │
│ ✅ Good for libraries │
│ │
│ CONS: │
│ ❌ Very verbose boilerplate │
│ ❌ Complex to write manually │
│ ❌ Mostly generated by bundlers now │
│ ❌ Being replaced by ESM + CJS dual packages │
│ │
│ STATUS: Still used for library distribution, but declining │
│ │
└─────────────────────────────────────────────────────────────────────┘
5. ES6 Modules (ESM) - The Standard
Native JavaScript modules (covered in detail above).
// math.mjs (ES Module)
export const PI = 3.14159;
export function add(a, b) {
return a + b;
}
export function multiply(a, b) {
return a * b;
}
// Default export
export default class Calculator {
add(a, b) {
return a + b;
}
}
// main.mjs (ES Module consumer)
import Calculator, { PI, add, multiply } from './math.mjs';
import * as math from './math.mjs';
console.log(add(2, 3)); // Named import
console.log(math.PI); // Namespace import
const calc = new Calculator(); // Default import
// Dynamic import
const module = await import('./math.mjs');
┌─────────────────────────────────────────────────────────────────────┐
│ ES6 MODULES (ESM) │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ SYNTAX: │
│ import { x } from './mod.js' // Named import │
│ import x from './mod.js' // Default import │
│ import * as mod from './mod' // Namespace import │
│ export const x = 1 // Named export │
│ export default x // Default export │
│ export { x, y } // Export list │
│ │
│ THE STANDARD: │
│ • Part of ECMAScript specification │
│ • Native browser support │
│ • Native Node.js support (v12+) │
│ • Static structure enables optimization │
│ │
│ KEY FEATURES: │
│ ✓ Static analysis / tree-shaking │
│ ✓ Live bindings (not copies) │
│ ✓ Async loading │
│ ✓ Top-level await │
│ ✓ Strict mode by default │
│ │
│ FILE EXTENSIONS: .mjs or .js with "type": "module" │
│ │
└─────────────────────────────────────────────────────────────────────┘
6. NPM Package Module System
How npm packages expose modules.
// package.json
{
"name": "my-library",
"version": "1.0.0",
"type": "module",
"main": "./dist/index.cjs",
"module": "./dist/index.mjs",
"exports": {
".": {
"import": "./dist/index.mjs",
"require": "./dist/index.cjs",
"types": "./dist/index.d.ts"
},
"./utils": {
"import": "./dist/utils.mjs",
"require": "./dist/utils.cjs"
}
},
"files": ["dist"]
}
┌─────────────────────────────────────────────────────────────────────┐
│ NPM PACKAGE EXPORTS │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ PACKAGE.JSON FIELDS: │
│ │
│ "type": "module" → Treat .js as ESM │
│ "type": "commonjs" → Treat .js as CJS (default) │
│ │
│ "main" → CJS entry point (legacy) │
│ "module" → ESM entry point (bundlers) │
│ "browser" → Browser-specific entry │
│ "exports" → Modern entry points (recommended) │
│ │
│ EXPORTS FIELD (Modern): │
│ ──────────────────────── │
│ "exports": { │
│ ".": { // Main entry │
│ "import": "...", // ESM import │
│ "require": "...", // CJS require │
│ "types": "...", // TypeScript │
│ "default": "..." // Fallback │
│ }, │
│ "./subpath": {...} // Subpath exports │
│ } │
│ │
│ DUAL PACKAGE PATTERN: │
│ Publish both ESM and CJS for maximum compatibility │
│ │
└─────────────────────────────────────────────────────────────────────┘
7. Bundler-Based Modules
Modern bundlers transform and optimize modules.
┌─────────────────────────────────────────────────────────────────────┐
│ BUNDLER-BASED MODULES │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ BUNDLERS: │
│ │
│ WEBPACK │
│ ├─ Most configurable │
│ ├─ Code splitting, lazy loading │
│ ├─ Loaders for any file type │
│ └─ Large plugin ecosystem │
│ │
│ ROLLUP │
│ ├─ Best tree-shaking │
│ ├─ Optimized for libraries │
│ ├─ ESM-first design │
│ └─ Smaller output bundles │
│ │
│ VITE │
│ ├─ Uses native ESM in development │
│ ├─ Extremely fast HMR │
│ ├─ Rollup for production builds │
│ └─ Zero-config for most projects │
│ │
│ PARCEL │
│ ├─ Zero configuration │
│ ├─ Built-in transforms │
│ └─ Good for quick prototypes │
│ │
│ esbuild │
│ ├─ Extremely fast (Go-based) │
│ ├─ Basic but efficient │
│ └─ Often used by other tools │
│ │
└─────────────────────────────────────────────────────────────────────┘
// Webpack example - webpack.config.js
module.exports = {
entry: './src/index.js',
output: {
filename: 'bundle.js',
path: path.resolve(__dirname, 'dist'),
},
module: {
rules: [{ test: /\.js$/, use: 'babel-loader' }],
},
optimization: {
splitChunks: { chunks: 'all' },
},
};
// Vite example - vite.config.js
import { defineConfig } from 'vite';
export default defineConfig({
build: {
rollupOptions: {
input: 'src/main.js',
output: {
manualChunks: {
vendor: ['lodash', 'axios'],
},
},
},
},
});
8. Babel-Transpiled Modules
Babel transforms modern module syntax for older environments.
// Input: ES Modules
import { add } from './math.js';
export const result = add(1, 2);
// Output: CommonJS (after Babel)
('use strict');
Object.defineProperty(exports, '__esModule', { value: true });
exports.result = void 0;
var _math = require('./math.js');
var result = (0, _math.add)(1, 2);
exports.result = result;
┌─────────────────────────────────────────────────────────────────────┐
│ BABEL MODULE TRANSFORMS │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ COMMON TRANSFORMS: │
│ │
│ @babel/plugin-transform-modules-commonjs │
│ → ESM to CJS │
│ │
│ @babel/plugin-transform-modules-amd │
│ → ESM to AMD │
│ │
│ @babel/plugin-transform-modules-umd │
│ → ESM to UMD │
│ │
│ @babel/plugin-transform-modules-systemjs │
│ → ESM to SystemJS │
│ │
│ INTEROP HELPERS: │
│ __esModule marker │
│ _interopRequireDefault │
│ _interopRequireWildcard │
│ │
│ PURPOSE: │
│ Write modern ESM → Babel transforms to target format │
│ Ensures compatibility with older Node.js/browsers │
│ │
└─────────────────────────────────────────────────────────────────────┘
9. Top-Level Await (ESM Feature)
Covered in detail above. Key points:
// config.js (ESM with Top-Level Await)
const response = await fetch('/api/config');
export const config = await response.json();
// database.js
export const db = await connectToDatabase();
// main.js
import { config } from './config.js'; // Waits for config to load
import { db } from './database.js'; // Waits for connection
// Both are guaranteed ready here
console.log(config.apiUrl);
await db.query('SELECT * FROM users');
Module Systems Comparison
┌──────────────────────────────────────────────────────────────────────────────┐
│ MODULE SYSTEMS COMPARISON │
├──────────────┬─────────┬─────────┬─────────┬─────────┬─────────┬────────────┤
│ Feature │ IIFE │ CJS │ AMD │ UMD │ ESM │ Bundler │
├──────────────┼─────────┼─────────┼─────────┼─────────┼─────────┼────────────┤
│ Async Load │ ❌ │ ❌ │ ✅ │ ❌ │ ✅ │ ✅ │
│ Tree-shake │ ❌ │ ❌ │ ❌ │ ❌ │ ✅ │ ✅ │
│ Live Binding │ ❌ │ ❌ │ ❌ │ ❌ │ ✅ │ ✅ │
│ Static │ ❌ │ ❌ │ ✅ │ ❌ │ ✅ │ ✅ │
│ Browser │ ✅ │ ❌ │ ✅ │ ✅ │ ✅ │ ✅ │
│ Node.js │ ✅ │ ✅ │ ❌ │ ✅ │ ✅ │ ✅ │
│ Dynamic │ ✅ │ ✅ │ ✅ │ ✅ │ ✅* │ ✅ │
│ No Build │ ✅ │ ✅ │ ✅ │ ✅ │ ✅ │ ❌ │
├──────────────┼─────────┴─────────┴─────────┴─────────┴─────────┴────────────┤
│ Status │ Legacy │ Legacy │ Obsolete│ Fading │ Standard│ Modern │
└──────────────┴──────────────────────────────────────────────────────────────┘
* ESM dynamic import via import()
Which Module System to Use?
┌─────────────────────────────────────────────────────────────────────┐
│ DECISION GUIDE │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ NEW PROJECT (2024+): │
│ ──────────────────── │
│ → Use ES Modules (ESM) everywhere │
│ → Use a modern bundler (Vite, esbuild) │
│ → Set "type": "module" in package.json │
│ │
│ LIBRARY/PACKAGE: │
│ ──────────────── │
│ → Publish dual CJS + ESM (exports field) │
│ → Use Rollup or unbuild for bundling │
│ → Include TypeScript types │
│ │
│ LEGACY PROJECT: │
│ ─────────────── │
│ → Keep existing CommonJS if stable │
│ → Migrate gradually to ESM │
│ → Use Babel for interop if needed │
│ │
│ BROWSER-ONLY SCRIPT: │
│ ──────────────────── │
│ → ESM with <script type="module"> │
│ → Or Vite for development with HMR │
│ │
│ AVOID: │
│ ────── │
│ → AMD (obsolete) │
│ → UMD (complex, declining) │
│ → IIFE for anything beyond small scripts │
│ │
└─────────────────────────────────────────────────────────────────────┘
Key Takeaways
┌─────────────────────────────────────────────────────────────────────┐
│ ES MODULES SUMMARY │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ THREE PHASES: │
│ 1. Construction: Parse and build dependency graph │
│ 2. Instantiation: Link exports and imports (live bindings) │
│ 3. Evaluation: Execute code depth-first, post-order │
│ │
│ LIVE BINDINGS: │
│ • Imports are references to exports │
│ • Changes in exporting module are visible to importers │
│ • Read-only in importing module │
│ │
│ CIRCULAR DEPENDENCIES: │
│ • Handled but may see undefined for uninitialized exports │
│ • Use functions for deferred access │
│ │
│ CACHING: │
│ • Each module evaluated once │
│ • Same instance shared by all importers │
│ • Natural singleton pattern │
│ │
│ BEST PRACTICES: │
│ ✅ Use named exports for better tree-shaking │
│ ✅ Keep module side effects minimal │
│ ✅ Use dynamic import for code splitting │
│ ✅ Avoid circular dependencies when possible │
│ ✅ Use TLA sparingly (it blocks dependent modules) │
│ │
└─────────────────────────────────────────────────────────────────────┘
Next Steps
Continue to 22.5 Performance & Optimization Internals to learn about optimization killers, deoptimization triggers, and how to write highly performant JavaScript.