Docs
README
14.1 Module Systems Overview
📖 Introduction
Before ES6 modules, JavaScript had no built-in module system. Developers created various solutions to organize code into reusable, maintainable pieces. Understanding these systems helps you work with legacy code and appreciate why ES Modules became the standard.
┌─────────────────────────────────────────────────────────────────────────────┐
│ EVOLUTION OF JAVASCRIPT MODULES │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ 1995-2009 2009-2015 2015-Present Future │
│ ┌─────────┐ ┌─────────┐ ┌─────────────┐ ┌──────────┐ │
│ │ Global │ ──▶ │CommonJS │ ──▶ │ ES Modules │ ▶▶ │ Import │ │
│ │ Scripts │ │ AMD │ │ (ESM) │ │ Maps │ │
│ │ IIFE │ │ UMD │ │ │ │ │ │
│ └─────────┘ └─────────┘ └─────────────┘ └──────────┘ │
│ │
│ Problems: Solutions: Standard: Enhanced: │
│ • Globals • Node.js • Native • Dynamic │
│ • Collisions • Browsers • Static • Lazy load │
│ • Dependencies • Bundlers • Tree-shake • Federated │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
🎯 Learning Objectives
By the end of this section, you will:
- •✅ Understand why modules are essential in JavaScript
- •✅ Know the history and evolution of module systems
- •✅ Compare different module formats (IIFE, CommonJS, AMD, UMD, ESM)
- •✅ Recognize which system to use in different environments
- •✅ Understand how bundlers bridge different module systems
1️⃣ The Problem: Why We Need Modules
Before Modules: The Global Nightmare
// file1.js
var userName = 'Alice';
var userAge = 25;
function greet() {
console.log('Hello, ' + userName);
}
// file2.js - OOPS! Overwrites file1's variables!
var userName = 'Bob'; // 💥 Collision!
var greet = 'Hi there'; // 💥 Function overwritten!
// file3.js - Which userName? Which greet?
greet(); // TypeError: greet is not a function
┌─────────────────────────────────────────────────────────────────────┐
│ THE GLOBAL SCOPE PROBLEM │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ <script src="jquery.js"></script> ─┐ │
│ <script src="lodash.js"></script> │ │
│ <script src="utils.js"></script> ├─▶ ALL share ONE │
│ <script src="app.js"></script> │ global namespace! │
│ <script src="analytics.js"></script> ─┘ │
│ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ GLOBAL NAMESPACE (window) │ │
│ │ ┌────────┬────────┬────────┬────────┬────────────────┐ │ │
│ │ │ $ │ _ │ utils │ app │ gtag ... │ │ │
│ │ │(jQuery)│(lodash)│ │ │ │ │ │
│ │ └────────┴────────┴────────┴────────┴────────────────┘ │ │
│ │ │ │
│ │ Problems: │ │
│ │ • Name collisions (multiple libs use same names) │ │
│ │ • Implicit dependencies (load order matters!) │ │
│ │ • No encapsulation (everything is public) │ │
│ │ • Hard to maintain and test │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────┘
What Modules Solve
| Problem | Without Modules | With Modules |
|---|---|---|
| Namespace | Everything global | Private by default |
| Dependencies | Implicit (script order) | Explicit (import/export) |
| Reusability | Copy-paste code | Import and reuse |
| Encapsulation | All variables public | Choose what to expose |
| Maintainability | Spaghetti code | Clear structure |
| Testing | Hard to isolate | Easy to mock |
2️⃣ Early Solutions: IIFE Pattern
Immediately Invoked Function Expression
Before module systems, developers used IIFEs (Immediately Invoked Function Expressions) to create private scope:
// The IIFE Pattern - Creating Private Scope
var MyModule = (function () {
// Private variables - not accessible outside
var privateCounter = 0;
var privateData = 'secret';
// Private function
function privateLog(msg) {
console.log('[Private]:', msg);
}
// Return public API (Revealing Module Pattern)
return {
// Public method
increment: function () {
privateCounter++;
privateLog('Counter is now ' + privateCounter);
},
// Public method
getCount: function () {
return privateCounter;
},
// Public property
version: '1.0.0',
};
})();
// Usage
MyModule.increment(); // [Private]: Counter is now 1
console.log(MyModule.getCount()); // 1
console.log(MyModule.version); // "1.0.0"
console.log(MyModule.privateCounter); // undefined (private!)
┌─────────────────────────────────────────────────────────────────────┐
│ IIFE PATTERN │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ (function() { ◀── Immediately invoked │
│ │ │
│ │ ┌─────────────────────────────────────┐ │
│ │ │ PRIVATE SCOPE │ │
│ │ │ ┌─────────────────────────────┐ │ │
│ │ │ │ var secret = "hidden"; │ │ │
│ │ │ │ function helper() {...} │ │ Not accessible │
│ │ │ │ var internalState = {}; │ │ from outside │
│ │ │ └─────────────────────────────┘ │ │
│ │ └─────────────────────────────────────┘ │
│ │ │
│ │ return { ◀── Only these are exposed │
│ │ publicMethod: function() {...}, │
│ │ publicProperty: value │
│ │ }; │
│ │ │
│ })(); │
│ │
│ ┌─────────────────────────────────────┐ │
│ │ ✓ Creates private scope │ │
│ │ ✓ Exposes only public API │ │
│ │ ✗ Still uses one global variable │ │
│ │ ✗ No dependency management │ │
│ │ ✗ Manual ordering of scripts │ │
│ └─────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────┘
IIFE with Dependencies
// Passing dependencies to IIFE
var MyApp = (function ($, _, config) {
// $ is jQuery, _ is Lodash, config is our config object
function init() {
$('.container').html(_.template('<h1><%= title %></h1>')(config));
}
return { init: init };
})(jQuery, lodash, AppConfig); // Pass dependencies
// Still requires correct script loading order!
// <script src="jquery.js"></script>
// <script src="lodash.js"></script>
// <script src="config.js"></script>
// <script src="myapp.js"></script> ← Must be last!
3️⃣ CommonJS (CJS)
Created for Node.js (2009)
CommonJS was designed for server-side JavaScript (Node.js) where files are loaded from disk synchronously.
// ═══════════════════════════════════════════════════════════════
// math.js - Exporting a module
// ═══════════════════════════════════════════════════════════════
// Private to this module
const PI = 3.14159;
const E = 2.71828;
// Public functions
function add(a, b) {
return a + b;
}
function multiply(a, b) {
return a * b;
}
function circleArea(radius) {
return PI * radius * radius;
}
// Export public API
module.exports = {
add,
multiply,
circleArea,
PI, // Can also export constants
};
// Alternative: Export individual items
// exports.add = add;
// exports.multiply = multiply;
// ═══════════════════════════════════════════════════════════════
// app.js - Importing the module
// ═══════════════════════════════════════════════════════════════
// Import entire module
const math = require('./math');
console.log(math.add(2, 3)); // 5
console.log(math.circleArea(10)); // 314.159
console.log(math.PI); // 3.14159
// Destructuring import
const { add, multiply } = require('./math');
console.log(add(5, 5)); // 10
console.log(multiply(4, 3)); // 12
┌─────────────────────────────────────────────────────────────────────┐
│ COMMONJS FLOW │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────┐ ┌──────────────┐ │
│ │ math.js │ │ app.js │ │
│ ├──────────────┤ ├──────────────┤ │
│ │ │ │ │ │
│ │ const PI=3.14│ │ const math = │ │
│ │ │ ◀────── │ require │ │
│ │ function add │ │ ('./math') │ │
│ │ function mul │ │ │ │
│ │ │ │ math.add() │ │
│ │ module. │ ──────▶ │ math.PI │ │
│ │ exports={ │ │ │ │
│ │ add, mul, │ │ │ │
│ │ PI │ │ │ │
│ │ } │ │ │ │
│ └──────────────┘ └──────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ HOW require() WORKS: │ │
│ │ │ │
│ │ 1. Resolve: Find the file path │ │
│ │ 2. Load: Read file from disk (synchronous!) │ │
│ │ 3. Wrap: Wrap in function with module, exports, require │ │
│ │ 4. Execute: Run the wrapped code │ │
│ │ 5. Cache: Store result for future require() calls │ │
│ │ 6. Return: Return module.exports │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
│ Characteristics: │
│ ✓ Synchronous loading (good for server, file system) │
│ ✓ Simple syntax │
│ ✓ Caching built-in │
│ ✗ Not suitable for browsers (synchronous = blocking) │
│ ✗ Dynamic - can't be statically analyzed │
│ │
└─────────────────────────────────────────────────────────────────────┘
CommonJS Dynamic Nature
// CommonJS allows dynamic requires (but not recommended)
const moduleName = someCondition ? 'moduleA' : 'moduleB';
const dynamicModule = require(`./${moduleName}`);
// Conditional requires
if (process.env.NODE_ENV === 'development') {
const debug = require('debug-module');
debug.enable();
}
// require() can be called anywhere
function loadPlugin(name) {
return require(`./plugins/${name}`);
}
4️⃣ AMD (Asynchronous Module Definition)
Designed for Browsers (2010)
AMD was created specifically for browsers where asynchronous loading is essential to prevent blocking the page.
// ═══════════════════════════════════════════════════════════════
// math.js - Define an AMD module
// ═══════════════════════════════════════════════════════════════
define('math', [], function () {
// Module code
const PI = 3.14159;
function add(a, b) {
return a + b;
}
function multiply(a, b) {
return a * b;
}
// Return public API
return {
add: add,
multiply: multiply,
PI: PI,
};
});
// ═══════════════════════════════════════════════════════════════
// app.js - Require AMD modules
// ═══════════════════════════════════════════════════════════════
// Require with dependencies
require(['jquery', 'math', 'utils'], function ($, math, utils) {
// All dependencies loaded asynchronously
// This callback runs when ALL are ready
$('.result').text(math.add(10, 20));
utils.log('Calculation complete!');
});
// Module with dependencies
define('calculator', ['math', 'logger'], function (math, logger) {
// math and logger are loaded first
function calculate(a, b, operation) {
logger.log(`Calculating ${a} ${operation} ${b}`);
switch (operation) {
case '+':
return math.add(a, b);
case '*':
return math.multiply(a, b);
default:
throw new Error('Unknown operation');
}
}
return { calculate };
});
┌─────────────────────────────────────────────────────────────────────┐
│ AMD LOADING │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ require(['A', 'B', 'C'], function(A, B, C) { ... }); │
│ │
│ ┌────────────────────────────────────────────────────────┐ │
│ │ BROWSER │ │
│ │ │ │
│ │ ┌─────┐ ┌─────┐ ┌─────┐ │ │
│ │ │ A │ │ B │ │ C │ ← Parallel Load │ │
│ │ └──┬──┘ └──┬──┘ └──┬──┘ │ │
│ │ │ │ │ │ │
│ │ ▼ ▼ ▼ │ │
│ │ ┌─────────────────────────────┐ │ │
│ │ │ Wait for ALL to load │ │ │
│ │ └─────────────┬───────────────┘ │ │
│ │ │ │ │
│ │ ▼ │ │
│ │ ┌─────────────────────────────┐ │ │
│ │ │ Execute callback with │ │ │
│ │ │ resolved dependencies │ │ │
│ │ └─────────────────────────────┘ │ │
│ │ │ │
│ └────────────────────────────────────────────────────────┘ │
│ │
│ Characteristics: │
│ ✓ Asynchronous (non-blocking) │
│ ✓ Parallel loading │
│ ✓ Designed for browsers │
│ ✓ RequireJS is the main implementation │
│ ✗ Verbose syntax │
│ ✗ Wrapper function required │
│ ✗ Less popular now (ESM replaced it) │
│ │
└─────────────────────────────────────────────────────────────────────┘
5️⃣ UMD (Universal Module Definition)
Works Everywhere
UMD is a hybrid format that works in CommonJS (Node.js), AMD (RequireJS), and as a global variable (browser scripts).
// ═══════════════════════════════════════════════════════════════
// UMD Pattern - Universal Module Definition
// ═══════════════════════════════════════════════════════════════
(function (root, factory) {
if (typeof define === 'function' && define.amd) {
// AMD environment (RequireJS)
define(['dependency'], factory);
} else if (typeof module === 'object' && module.exports) {
// CommonJS environment (Node.js)
module.exports = factory(require('dependency'));
} else {
// Browser globals
root.MyLibrary = factory(root.Dependency);
}
})(typeof self !== 'undefined' ? self : this, function (dependency) {
// Module code here
function greet(name) {
return `Hello, ${name}!`;
}
function farewell(name) {
return `Goodbye, ${name}!`;
}
// Return public API
return {
greet: greet,
farewell: farewell,
version: '1.0.0',
};
});
┌─────────────────────────────────────────────────────────────────────┐
│ UMD COMPATIBILITY │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────┐ │
│ │ UMD WRAPPER │ │
│ │ (Detects │ │
│ │ Environment) │ │
│ └────────┬────────┘ │
│ │ │
│ ┌────────────────┼────────────────┐ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ AMD │ │ CommonJS │ │ Global │ │
│ │ │ │ │ │ │ │
│ │ define() │ │ require()│ │ window. │ │
│ │ require()│ │ exports │ │ MyLib │ │
│ │ │ │ │ │ │ │
│ │ Browser │ │ Node.js │ │ Browser │ │
│ │ RequireJS│ │ │ │ <script> │ │
│ └──────────┘ └──────────┘ └──────────┘ │
│ │
│ When to use UMD: │
│ ✓ Publishing a library that works everywhere │
│ ✓ Supporting legacy environments │
│ ✓ When consumers use different module systems │
│ │
│ Modern alternative: │
│ • Build ESM + CJS + UMD versions with bundler │
│ • Let package.json "exports" field handle resolution │
│ │
└─────────────────────────────────────────────────────────────────────┘
6️⃣ ES Modules (ESM) - The Standard
Native JavaScript Modules (ES6/2015)
ES Modules are the official standard built into JavaScript itself.
// ═══════════════════════════════════════════════════════════════
// math.js - ES Module exports
// ═══════════════════════════════════════════════════════════════
// Named exports
export const PI = 3.14159;
export const E = 2.71828;
export function add(a, b) {
return a + b;
}
export function multiply(a, b) {
return a * b;
}
// Private (not exported)
function internalHelper() {
return "I'm private!";
}
// Default export (one per module)
export default class Calculator {
add(a, b) {
return a + b;
}
subtract(a, b) {
return a - b;
}
}
// ═══════════════════════════════════════════════════════════════
// app.js - ES Module imports
// ═══════════════════════════════════════════════════════════════
// Import named exports
import { add, multiply, PI } from './math.js';
// Import default export
import Calculator from './math.js';
// Import all as namespace
import * as math from './math.js';
// Rename imports
import { add as sum, multiply as product } from './math.js';
// Import both default and named
import Calculator, { PI, E } from './math.js';
// Usage
console.log(add(2, 3)); // 5
console.log(PI); // 3.14159
const calc = new Calculator();
console.log(calc.add(10, 5)); // 15
console.log(math.multiply(4, 5)); // 20
┌─────────────────────────────────────────────────────────────────────┐
│ ES MODULES - THE STANDARD │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ KEY FEATURES │ │
│ │ │ │
│ │ ✓ Static structure (analyzed at compile time) │ │
│ │ ✓ Tree-shaking (dead code elimination) │ │
│ │ ✓ Native browser support │ │
│ │ ✓ Async loading built-in │ │
│ │ ✓ Strict mode by default │ │
│ │ ✓ Top-level await (ES2022) │ │
│ │ ✓ Live bindings (exports are live references) │ │
│ └──────────────────────────────────────────────────────────┘ │
│ │
│ Static vs Dynamic: │
│ │
│ ┌─────────────────────┐ ┌─────────────────────┐ │
│ │ CommonJS │ │ ES Modules │ │
│ │ (Dynamic) │ │ (Static) │ │
│ ├─────────────────────┤ ├─────────────────────┤ │
│ │ │ │ │ │
│ │ // Works │ │ // ERROR! │ │
│ │ if (cond) { │ │ if (cond) { │ │
│ │ require('./a'); │ │ import './a'; │ │
│ │ } │ │ } │ │
│ │ │ │ │ │
│ │ // Works │ │ // Use dynamic │ │
│ │ require(variable); │ │ // import() instead │ │
│ │ │ │ import(variable); │ │
│ │ │ │ │ │
│ └─────────────────────┘ └─────────────────────┘ │
│ │
│ Static structure enables: │
│ • Tree-shaking (remove unused exports) │
│ • Static analysis (IDE support, type checking) │
│ • Faster loading (parallel fetch) │
│ │
└─────────────────────────────────────────────────────────────────────┘
7️⃣ Module Systems Comparison
┌─────────────────────────────────────────────────────────────────────────────────┐
│ MODULE SYSTEMS COMPARISON │
├──────────┬──────────────┬──────────────┬──────────────┬─────────────────────────┤
│ Feature │ CommonJS │ AMD │ UMD │ ES Modules │
├──────────┼──────────────┼──────────────┼──────────────┼─────────────────────────┤
│ Syntax │ require() │ define() │ (complex) │ import/export │
│ │ exports │ require() │ │ │
├──────────┼──────────────┼──────────────┼──────────────┼─────────────────────────┤
│ Loading │ Synchronous │ Asynchronous │ Depends │ Asynchronous │
├──────────┼──────────────┼──────────────┼──────────────┼─────────────────────────┤
│ Analysis │ Dynamic │ Dynamic │ Dynamic │ Static │
├──────────┼──────────────┼──────────────┼──────────────┼─────────────────────────┤
│ Tree │ ❌ No │ ❌ No │ ❌ No │ ✅ Yes │
│ Shaking │ │ │ │ │
├──────────┼──────────────┼──────────────┼──────────────┼─────────────────────────┤
│ Browser │ ❌ Needs │ ✅ Yes │ ✅ Yes │ ✅ Yes (native) │
│ Support │ bundler │ (RequireJS) │ │ │
├──────────┼──────────────┼──────────────┼──────────────┼─────────────────────────┤
│ Node.js │ ✅ Native │ ❌ No │ ✅ Yes │ ✅ Yes (.mjs or │
│ Support │ │ │ │ "type":"module") │
├──────────┼──────────────┼──────────────┼──────────────┼─────────────────────────┤
│ Usage │ Node.js, │ Legacy │ Universal │ Modern JS │
│ Today │ Legacy │ browser │ libraries │ Standard │
├──────────┼──────────────┼──────────────┼──────────────┼─────────────────────────┤
│ Future │ Declining │ Deprecated │ Still used │ ✅ THE STANDARD │
│ │ │ │ for libs │ │
└──────────┴──────────────┴──────────────┴──────────────┴─────────────────────────┘
8️⃣ When to Use Which
┌─────────────────────────────────────────────────────────────────────┐
│ CHOOSING A MODULE SYSTEM │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ NEW PROJECT? │ │
│ │ │ │
│ │ → USE ES MODULES │ │
│ │ • Modern standard │ │
│ │ • Best tooling support │ │
│ │ • Tree-shaking │ │
│ │ • Works in browsers and Node.js │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ LEGACY NODE.JS PROJECT? │ │
│ │ │ │
│ │ → COMMONJS is fine │ │
│ │ • Existing codebase uses it │ │
│ │ • Can migrate to ESM gradually │ │
│ │ • Set "type": "module" in package.json to use ESM │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ PUBLISHING A LIBRARY? │ │
│ │ │ │
│ │ → BUILD MULTIPLE FORMATS │ │
│ │ • ESM for modern bundlers (tree-shaking) │ │
│ │ • CJS for Node.js compatibility │ │
│ │ • Use package.json "exports" field │ │
│ │ │ │
│ │ package.json: │ │
│ │ { │ │
│ │ "main": "./dist/index.cjs", │ │
│ │ "module": "./dist/index.mjs", │ │
│ │ "exports": { │ │
│ │ "import": "./dist/index.mjs", │ │
│ │ "require": "./dist/index.cjs" │ │
│ │ } │ │
│ │ } │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────┘
9️⃣ Summary
┌─────────────────────────────────────────────────────────────────────┐
│ KEY TAKEAWAYS │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ 📜 HISTORY: │
│ Global scripts → IIFE → CommonJS/AMD → UMD → ES Modules │
│ │
│ 🎯 ES MODULES ARE THE FUTURE: │
│ • Native JavaScript standard │
│ • Supported in all modern browsers and Node.js │
│ • Enable tree-shaking and static analysis │
│ • Use import/export syntax │
│ │
│ 🔧 COMMONJS STILL MATTERS: │
│ • Used in older Node.js code │
│ • Many npm packages still use it │
│ • require()/module.exports syntax │
│ │
│ 📦 BUNDLERS BRIDGE THE GAP: │
│ • Webpack, Rollup, Vite, esbuild │
│ • Convert between module formats │
│ • Enable ESM in older browsers │
│ │
│ 🚀 RECOMMENDATION: │
│ • New projects: Use ES Modules │
│ • Libraries: Build both ESM and CJS │
│ • Legacy: Migrate gradually to ESM │
│ │
└─────────────────────────────────────────────────────────────────────┘
📚 Next Steps
Continue to 14.2 ES Modules Syntax to learn:
- •All import/export variations
- •Dynamic imports
- •Module aggregation
- •Top-level await