Docs
README
14.2 ES Modules Syntax
📖 Introduction
ES Modules (ESM) provide a standardized, powerful syntax for organizing JavaScript code. This section covers every aspect of the import and export keywords, from basic usage to advanced patterns.
┌─────────────────────────────────────────────────────────────────────────────┐
│ ES MODULES SYNTAX OVERVIEW │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ EXPORTING IMPORTING │
│ ───────── ───────── │
│ │
│ ┌─────────────────┐ ┌─────────────────┐ │
│ │ Named Export │ ◀──────────────▶ │ Named Import │ │
│ │ export { x } │ │ import { x } │ │
│ └─────────────────┘ └─────────────────┘ │
│ │
│ ┌─────────────────┐ ┌─────────────────┐ │
│ │ Default Export │ ◀──────────────▶ │ Default Import │ │
│ │ export default │ │ import x from │ │
│ └─────────────────┘ └─────────────────┘ │
│ │
│ ┌─────────────────┐ ┌─────────────────┐ │
│ │ Re-export │ ◀──────────────▶ │ Namespace Import│ │
│ │ export { } from │ │ import * as │ │
│ └─────────────────┘ └─────────────────┘ │
│ │
│ ┌─────────────────┐ ┌─────────────────┐ │
│ │ │ │ Dynamic Import │ │
│ │ │ ◀──────────────▶ │ import() │ │
│ │ │ │ (returns Promise)│ │
│ └─────────────────┘ └─────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
🎯 Learning Objectives
By the end of this section, you will:
- •✅ Master all export syntax variations
- •✅ Understand all import syntax patterns
- •✅ Use dynamic imports for code splitting
- •✅ Re-export and aggregate modules
- •✅ Handle circular dependencies
- •✅ Use top-level await
1️⃣ Named Exports
Basic Named Exports
// ═══════════════════════════════════════════════════════════════
// utils.js - Named exports
// ═══════════════════════════════════════════════════════════════
// Export at declaration
export const PI = 3.14159;
export const E = 2.71828;
export let counter = 0; // Can export let (live binding)
export function add(a, b) {
return a + b;
}
export function subtract(a, b) {
return a - b;
}
export class Calculator {
add(a, b) {
return a + b;
}
subtract(a, b) {
return a - b;
}
}
// Export arrow function
export const multiply = (a, b) => a * b;
Export List (After Declaration)
// ═══════════════════════════════════════════════════════════════
// math.js - Export list pattern
// ═══════════════════════════════════════════════════════════════
// Declare first
const PI = 3.14159;
const E = 2.71828;
function add(a, b) {
return a + b;
}
function subtract(a, b) {
return a - b;
}
function internalHelper() {
// This stays private (not exported)
return "I'm internal!";
}
// Export at the end (preferred for readability)
export { PI, E, add, subtract };
// You can also rename while exporting
export { add as sum, subtract as difference };
┌─────────────────────────────────────────────────────────────────────┐
│ NAMED EXPORTS │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ Two Styles: │
│ │
│ ┌─────────────────────────┐ ┌─────────────────────────┐ │
│ │ INLINE EXPORT │ │ EXPORT LIST │ │
│ │ │ │ │ │
│ │ export const x = 1; │ │ const x = 1; │ │
│ │ export function f() │ │ function f() {...} │ │
│ │ export class C │ │ class C {...} │ │
│ │ │ │ │ │
│ │ ✓ Export immediately │ │ export { x, f, C }; │ │
│ │ ✓ Clear what's public │ │ │ │
│ │ │ │ ✓ All exports visible │ │
│ │ │ │ ✓ Rename on export │ │
│ └─────────────────────────┘ └─────────────────────────┘ │
│ │
│ RENAMING: │
│ │
│ export { localName as exportedName }; │
│ │
│ // Example │
│ const internalAdd = (a, b) => a + b; │
│ export { internalAdd as add }; // Exported as 'add' │
│ │
└─────────────────────────────────────────────────────────────────────┘
2️⃣ Named Imports
// ═══════════════════════════════════════════════════════════════
// app.js - Named imports
// ═══════════════════════════════════════════════════════════════
// Basic named import
import { add, subtract } from './math.js';
// Import with alias (rename)
import { add as sum, subtract as minus } from './math.js';
// Import multiple
import { PI, E, add, subtract, Calculator } from './utils.js';
// Namespace import (import all as object)
import * as math from './math.js';
// Usage: math.add(), math.PI, etc.
// Mixed: You can combine patterns
import { add }, * as utils from './utils.js'; // ❌ Invalid!
// Instead, import separately or use namespace only
┌─────────────────────────────────────────────────────────────────────┐
│ NAMED IMPORTS │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ IMPORT SYNTAX PATTERNS │ │
│ ├─────────────────────────────────────────────────────────┤ │
│ │ │ │
│ │ import { a, b, c } from './module.js'; │ │
│ │ ▲ ▲ ▲ │ │
│ │ │ │ │ │ │
│ │ └──┴──┴── Must match export names exactly │ │
│ │ │ │
│ │ import { a as x } from './module.js'; │ │
│ │ ▲ ▲ │ │
│ │ │ └── Local name (use 'x' in this file) │ │
│ │ └─────── Original export name │ │
│ │ │ │
│ │ import * as mod from './module.js'; │ │
│ │ ▲ │ │
│ │ └── All exports as properties of 'mod' │ │
│ │ mod.a, mod.b, mod.c, mod.default │ │
│ │ │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
│ Common Mistakes: │
│ │
│ import { Add } from './math.js'; // ❌ Case sensitive! │
│ import { add } from './math.js'; // ✅ Correct │
│ │
│ import { add } from 'math.js'; // ❌ Missing ./ │
│ import { add } from './math.js'; // ✅ Relative path │
│ │
│ import { add } from './math'; // ⚠️ Might work (bundler) │
│ import { add } from './math.js'; // ✅ Include extension │
│ │
└─────────────────────────────────────────────────────────────────────┘
3️⃣ Default Exports
Exporting Default
// ═══════════════════════════════════════════════════════════════
// logger.js - Default export (ONE per module)
// ═══════════════════════════════════════════════════════════════
// Method 1: Export default class
export default class Logger {
log(msg) {
console.log(`[LOG]: ${msg}`);
}
error(msg) {
console.error(`[ERROR]: ${msg}`);
}
warn(msg) {
console.warn(`[WARN]: ${msg}`);
}
}
// ═══════════════════════════════════════════════════════════════
// api.js - Default export function
// ═══════════════════════════════════════════════════════════════
export default function fetchData(url) {
return fetch(url).then(r => r.json());
}
// ═══════════════════════════════════════════════════════════════
// config.js - Default export object
// ═══════════════════════════════════════════════════════════════
export default {
apiUrl: 'https://api.example.com',
timeout: 5000,
retries: 3
};
// ═══════════════════════════════════════════════════════════════
// counter.js - Default export with named exports
// ═══════════════════════════════════════════════════════════════
let count = 0;
function increment() { return ++count; }
function decrement() { return --count; }
function getCount() { return count; }
// Named exports
export { increment, decrement };
// Default export
export default getCount;
Importing Default
// ═══════════════════════════════════════════════════════════════
// app.js - Importing default exports
// ═══════════════════════════════════════════════════════════════
// Import default - can use ANY name
import Logger from './logger.js'; // Class
import fetchData from './api.js'; // Function
import config from './config.js'; // Object
import getCount from './counter.js'; // Function
// You can name it anything (it's the DEFAULT)
import MyLogger from './logger.js'; // Same as Logger
import getData from './api.js'; // Same as fetchData
import settings from './config.js'; // Same as config
// Import default + named together
import getCount, { increment, decrement } from './counter.js';
// Alternative syntax for default
import { default as Logger } from './logger.js';
┌─────────────────────────────────────────────────────────────────────┐
│ DEFAULT vs NAMED EXPORTS │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ ┌───────────────────────┬───────────────────────┐ │
│ │ DEFAULT EXPORT │ NAMED EXPORTS │ │
│ ├───────────────────────┼───────────────────────┤ │
│ │ │ │ │
│ │ ONE per module │ MANY per module │ │
│ │ │ │ │
│ │ export default x │ export { a, b, c } │ │
│ │ │ │ │
│ │ import X from │ import { a, b, c } │ │
│ │ (any name) │ (exact names) │ │
│ │ │ │ │
│ │ No curly braces │ Curly braces │ │
│ │ │ required │ │
│ │ │ │ │
│ │ Good for: │ Good for: │ │
│ │ • Main export │ • Utility functions │ │
│ │ • Single class │ • Constants │ │
│ │ • Config object │ • Multiple exports │ │
│ │ │ │ │
│ └───────────────────────┴───────────────────────┘ │
│ │
│ You CAN have both in the same module: │
│ │
│ // module.js │
│ export const helper = () => {}; // Named │
│ export const CONSTANT = 42; // Named │
│ export default class Main {} // Default │
│ │
│ // import.js │
│ import Main, { helper, CONSTANT } from './module.js'; │
│ │
└─────────────────────────────────────────────────────────────────────┘
4️⃣ Re-exports (Aggregating Modules)
Creating a Barrel File (index.js)
// ═══════════════════════════════════════════════════════════════
// utils/math.js
// ═══════════════════════════════════════════════════════════════
export const add = (a, b) => a + b;
export const subtract = (a, b) => a - b;
// ═══════════════════════════════════════════════════════════════
// utils/string.js
// ═══════════════════════════════════════════════════════════════
export const capitalize = (str) => str.charAt(0).toUpperCase() + str.slice(1);
export const lowercase = (str) => str.toLowerCase();
// ═══════════════════════════════════════════════════════════════
// utils/array.js
// ═══════════════════════════════════════════════════════════════
export const first = (arr) => arr[0];
export const last = (arr) => arr[arr.length - 1];
export default function shuffle(arr) {
/* ... */
}
// ═══════════════════════════════════════════════════════════════
// utils/index.js - BARREL FILE (Re-exports everything)
// ═══════════════════════════════════════════════════════════════
// Re-export all from math
export * from './math.js';
// Re-export all from string
export * from './string.js';
// Re-export all named exports from array
export * from './array.js';
// Re-export default with a name
export { default as shuffle } from './array.js';
// You can also rename while re-exporting
export { add as sum, subtract as minus } from './math.js';
// Re-export specific items only
export { capitalize } from './string.js';
// ═══════════════════════════════════════════════════════════════
// app.js - Using the barrel file
// ═══════════════════════════════════════════════════════════════
// Instead of multiple imports:
// import { add, subtract } from './utils/math.js';
// import { capitalize } from './utils/string.js';
// import { first, last } from './utils/array.js';
// Single import from barrel:
import {
add,
subtract,
capitalize,
first,
last,
shuffle,
} from './utils/index.js';
// Or even simpler (if index.js is the default):
import { add, capitalize, first } from './utils';
┌─────────────────────────────────────────────────────────────────────┐
│ BARREL FILES │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ WITHOUT BARREL: WITH BARREL: │
│ │
│ utils/ utils/ │
│ ├── math.js ├── math.js │
│ ├── string.js ├── string.js │
│ └── array.js ├── array.js │
│ └── index.js ← Barrel │
│ │
│ // Multiple imports // Single import │
│ import {a} from './utils/math' import { │
│ import {b} from './utils/str' a, b, c │
│ import {c} from './utils/arr' } from './utils' │
│ │
├─────────────────────────────────────────────────────────────────────┤
│ RE-EXPORT SYNTAX: │
│ │
│ export * from './module.js'; // All named exports │
│ export { a, b } from './module.js'; // Specific exports │
│ export { a as x } from './module.js'; // Rename │
│ export { default } from './module.js'; // Re-export default │
│ export { default as X } from './m.js'; // Default as named │
│ │
├─────────────────────────────────────────────────────────────────────┤
│ ⚠️ CAUTION: Tree-shaking │
│ │
│ Barrel files can hurt tree-shaking if: │
│ • You import from barrel but only use 1 export │
│ • Bundler can't eliminate unused code │
│ │
│ Solution: Direct imports for large modules │
│ import { specific } from './utils/specific.js' │
│ │
└─────────────────────────────────────────────────────────────────────┘
5️⃣ Dynamic Imports
Lazy Loading with import()
// ═══════════════════════════════════════════════════════════════
// Dynamic import returns a Promise
// ═══════════════════════════════════════════════════════════════
// Basic dynamic import
async function loadModule() {
const module = await import('./heavy-module.js');
module.doSomething();
}
// Conditional loading
async function loadFeature(featureName) {
if (featureName === 'charts') {
const { Chart } = await import('./features/charts.js');
return new Chart();
} else if (featureName === 'maps') {
const { Map } = await import('./features/maps.js');
return new Map();
}
}
// Load based on user action
document.getElementById('loadBtn').addEventListener('click', async () => {
const { heavyFunction } = await import('./heavy-module.js');
heavyFunction();
});
// Dynamic path (variable)
async function loadLocale(lang) {
const translations = await import(`./locales/${lang}.js`);
return translations.default;
}
// Error handling
async function safeLoad(modulePath) {
try {
const module = await import(modulePath);
return module;
} catch (error) {
console.error(`Failed to load ${modulePath}:`, error);
return null;
}
}
// ═══════════════════════════════════════════════════════════════
// Real-world example: Route-based code splitting
// ═══════════════════════════════════════════════════════════════
const routes = {
'/': () => import('./pages/Home.js'),
'/about': () => import('./pages/About.js'),
'/contact': () => import('./pages/Contact.js'),
'/dashboard': () => import('./pages/Dashboard.js'),
};
async function navigate(path) {
const loadPage = routes[path];
if (loadPage) {
const pageModule = await loadPage();
const Page = pageModule.default;
renderPage(new Page());
} else {
const { NotFound } = await import('./pages/NotFound.js');
renderPage(new NotFound());
}
}
// Listen for navigation
window.addEventListener('popstate', () => {
navigate(window.location.pathname);
});
┌─────────────────────────────────────────────────────────────────────┐
│ DYNAMIC IMPORTS │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ Static Import Dynamic Import │
│ ───────────── ────────────── │
│ import { x } from './m.js' const m = await import('./m.js') │
│ │
│ • Runs at parse time • Runs at runtime │
│ • Always loads • Loads on demand │
│ • Top-level only • Can use anywhere │
│ • Static path • Variable path okay │
│ │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ USE CASES FOR DYNAMIC IMPORT: │
│ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ 1. Code Splitting │ │
│ │ Load features only when needed │ │
│ │ → Reduces initial bundle size │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ 2. Conditional Loading │ │
│ │ if (admin) { await import('./admin.js') } │ │
│ │ → Load based on user/environment │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ 3. Route-based Loading │ │
│ │ Load page components on navigation │ │
│ │ → SPA performance optimization │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ 4. Dynamic Module Paths │ │
│ │ import(`./plugins/${name}.js`) │ │
│ │ → Plugin systems, i18n │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────┘
6️⃣ Top-Level Await (ES2022)
// ═══════════════════════════════════════════════════════════════
// config.js - Top-level await in ES Modules
// ═══════════════════════════════════════════════════════════════
// You can use await at the top level of a module!
// Fetch config at module load
const response = await fetch('/api/config');
export const config = await response.json();
// Dynamic import at top level
const { default: lodash } = await import('lodash');
export const _ = lodash;
// Database connection
const db = await connectToDatabase();
export { db };
// Conditional initialization
export const cache = process.env.USE_CACHE ? await initCache() : null;
// ═══════════════════════════════════════════════════════════════
// app.js - Using module with top-level await
// ═══════════════════════════════════════════════════════════════
// This import waits for config.js to finish loading
import { config, db } from './config.js';
// config is already resolved!
console.log(config.apiUrl);
// db connection is ready
await db.query('SELECT * FROM users');
┌─────────────────────────────────────────────────────────────────────┐
│ TOP-LEVEL AWAIT │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ BEFORE (ES2021 and earlier): AFTER (ES2022+): │
│ │
│ // Had to wrap in async IIFE // Direct await! │
│ let config; const config = await │
│ (async () => { fetch('/config') │
│ const res = await fetch(...) .then(r => r.json()); │
│ config = await res.json(); │
│ })(); export { config }; │
│ │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ HOW IT WORKS: │
│ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ │ │
│ │ Module A (has top-level await) │ │
│ │ ┌──────────────────────────────┐ │ │
│ │ │ const data = await fetch() │ ← Pauses here │ │
│ │ │ export { data } │ │ │
│ │ └──────────────────────────────┘ │ │
│ │ │ │ │
│ │ ▼ │ │
│ │ Module B (imports from A) │ │
│ │ ┌──────────────────────────────┐ │ │
│ │ │ import { data } from './A' │ ← Waits for A │ │
│ │ │ console.log(data) │ │ │
│ │ └──────────────────────────────┘ │ │
│ │ │ │
│ └──────────────────────────────────────────────────────┘ │
│ │
│ ⚠️ CAUTION: Can delay module loading │
│ • Only use when necessary │
│ • Consider fallbacks for slow operations │
│ │
└─────────────────────────────────────────────────────────────────────┘
7️⃣ Module Metadata
// ═══════════════════════════════════════════════════════════════
// import.meta - Module metadata object
// ═══════════════════════════════════════════════════════════════
// Get the URL of the current module
console.log(import.meta.url);
// "file:///home/user/project/src/module.js" (Node.js)
// "https://example.com/js/module.js" (Browser)
// Resolve relative paths
const imagePath = new URL('./image.png', import.meta.url);
console.log(imagePath.href);
// Check if this is the main module (Node.js)
if (import.meta.url === `file://${process.argv[1]}`) {
console.log('This is the entry point!');
}
// In Node.js 20.6+, there's also:
// import.meta.dirname - Directory of current module
// import.meta.filename - Full path of current module
// Environment-specific metadata
console.log(import.meta.env); // Vite
console.log(import.meta.hot); // Hot Module Replacement
8️⃣ Circular Dependencies
// ═══════════════════════════════════════════════════════════════
// Circular dependencies: A imports B, B imports A
// ═══════════════════════════════════════════════════════════════
// ─── a.js ───
import { b } from './b.js';
export const a = 'A';
console.log('In a.js, b =', b); // Works because of live bindings
// ─── b.js ───
import { a } from './a.js';
export const b = 'B';
console.log('In b.js, a =', a); // Might be undefined!
// ═══════════════════════════════════════════════════════════════
// Solution 1: Function wrapping (lazy access)
// ═══════════════════════════════════════════════════════════════
// ─── a.js ───
import { getB } from './b.js';
export const a = 'A';
export const getA = () => a;
console.log('In a.js, b =', getB()); // Always works
// ─── b.js ───
import { getA } from './a.js';
export const b = 'B';
export const getB = () => b;
console.log('In b.js, a =', getA()); // Always works
// ═══════════════════════════════════════════════════════════════
// Solution 2: Restructure to avoid circular dependency
// ═══════════════════════════════════════════════════════════════
// ─── shared.js (new file) ───
export const shared = 'Shared value';
// ─── a.js ───
import { shared } from './shared.js';
export const a = shared + ' from A';
// ─── b.js ───
import { shared } from './shared.js';
export const b = shared + ' from B';
┌─────────────────────────────────────────────────────────────────────┐
│ CIRCULAR DEPENDENCIES │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ PROBLEM: SOLUTIONS: │
│ │
│ ┌─────┐ ┌─────┐ 1. Use function wrappers │
│ │ A │ ──────▶ │ B │ (lazy evaluation) │
│ │ │ ◀────── │ │ │
│ └─────┘ └─────┘ 2. Restructure code │
│ (extract shared code) │
│ A imports B │
│ B imports A 3. Merge modules │
│ ⚠️ Risk of undefined! (if tightly coupled) │
│ │
│ WHY IT CAN FAIL: │
│ │
│ 1. JS loads A.js │
│ 2. A.js imports B.js → pause A, load B │
│ 3. B.js imports A.js → A not finished! Gets partial exports │
│ 4. B.js finishes │
│ 5. A.js continues │
│ │
│ Live bindings help (ESM exports are references, not copies) │
│ but accessing before initialization still fails. │
│ │
└─────────────────────────────────────────────────────────────────────┘
9️⃣ Best Practices Summary
┌─────────────────────────────────────────────────────────────────────┐
│ ES MODULES BEST PRACTICES │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ ✅ DO: │
│ │
│ • Use named exports for utilities (easier refactoring) │
│ • Use default exports for main class/component per file │
│ • Include .js extension in imports (browser compatible) │
│ • Use barrel files for clean public APIs │
│ • Use dynamic imports for large/optional features │
│ • Keep modules focused (single responsibility) │
│ │
│ ❌ AVOID: │
│ │
│ • Mixing default and many named exports (confusing) │
│ • Circular dependencies (restructure instead) │
│ • Giant barrel files (tree-shaking issues) │
│ • Mutating imported values (they're read-only bindings) │
│ • Side effects at module level (initialization issues) │
│ │
├─────────────────────────────────────────────────────────────────────┤
│ FILE ORGANIZATION: │
│ │
│ src/ │
│ ├── components/ │
│ │ ├── Button.js ← default export: class Button │
│ │ ├── Input.js ← default export: class Input │
│ │ └── index.js ← barrel: export { Button, Input } │
│ ├── utils/ │
│ │ ├── math.js ← named exports: add, subtract, etc │
│ │ ├── string.js ← named exports: capitalize, trim │
│ │ └── index.js ← barrel: export * from './...' │
│ └── index.js ← main entry point │
│ │
└─────────────────────────────────────────────────────────────────────┘
📚 Summary
| Syntax | Purpose | Example |
|---|---|---|
export const x | Named export | export const PI = 3.14; |
export { x, y } | Export list | export { add, subtract }; |
export default | Default export | export default class App {} |
export { x as y } | Rename export | export { add as sum }; |
export * from | Re-export all | export * from './utils.js'; |
import { x } | Named import | import { add } from './math.js'; |
import x from | Default import | import App from './App.js'; |
import * as x | Namespace import | import * as math from './math.js'; |
import() | Dynamic import | const m = await import('./m.js'); |
📚 Next Steps
Continue to 14.3 CommonJS & AMD to learn:
- •Detailed CommonJS patterns
- •AMD configuration with RequireJS
- •Interoperability between systems
- •Migration strategies