ES Modules

ES Modules — introduced in ES6 and now natively supported in all modern browsers and Node.js — are the official JavaScript module system. They let you split code across files with explicit import and export declarations, enabling tree-shaking, lazy loading, and clean dependency management. Modules solve the problems of global namespace pollution, dependency ordering, and code organisation that plagued pre-module JavaScript. In this lesson you will master named exports, default exports, barrel files, dynamic imports, and the module characteristics every developer needs to know.

Export and Import Syntax #

Named vs Default Export #

Module Characteristics #

Basic Example #

// ── math.js — named exports ───────────────────────────────────────────────
export const PI = 3.14159265;

export function add(a, b)      { return a + b; }
export function subtract(a, b) { return a - b; }
export function multiply(a, b) { return a * b; }
export function divide(a, b) {
    if (b === 0) throw new RangeError('Division by zero');
    return a / b;
}

const square = n => n ** 2;
const cube   = n => n ** 3;
export { square, cube };

// ── app.js — named imports ────────────────────────────────────────────────
import { PI, add, multiply, square }  from './math.js';
import { subtract as minus }          from './math.js';   // renamed

console.log(PI);            // 3.14159265
console.log(add(3, 4));     // 7
console.log(minus(10, 3));  // 7
console.log(square(5));     // 25

// ── user.js — default export ──────────────────────────────────────────────
export default class User {
    constructor(name, email) {
        this.name  = name;
        this.email = email;
        this.id    = crypto.randomUUID();
    }
    toJSON() { return { id: this.id, name: this.name, email: this.email }; }
    static fromJSON({ name, email }) { return new User(name, email); }
}

// ── main.js — mix default + named imports ────────────────────────────────
import User         from './user.js';    // default — any name you choose
import { add, PI } from './math.js';    // named — must match export

const alice = new User('Alice', 'alice@example.com');
console.log(alice.toJSON());

// ── utils/index.js — barrel file ─────────────────────────────────────────
export { add, subtract, multiply, divide, PI } from './math.js';
export { default as User }                     from './user.js';
export { formatDate, formatCurrency }          from './format.js';

// ── consumer.js — clean import from barrel ────────────────────────────────
import { add, User, formatDate } from './utils/index.js';
// One import instead of three separate path-specific imports

// ── Namespace import ──────────────────────────────────────────────────────
import * as MathUtils from './math.js';
console.log(MathUtils.add(2, 3));   // 5
console.log(MathUtils.PI);          // 3.14159265

// ── Dynamic import — lazy loading on demand ───────────────────────────────
async function loadChartLibrary() {
    // Only fetched and parsed when this function is called
    const { Chart } = await import('./chart.js');
    return new Chart(document.querySelector('#canvas'));
}

// Conditional loading — can use variables in the path
async function loadEditor(type) {
    const module = await import(`./editors/${type}-editor.js`);
    return module.default;   // get the default export
}

// Code splitting — load heavy libraries only when needed
document.querySelector('#export-btn').addEventListener('click', async () => {
    const { generatePDF } = await import('./pdf-generator.js');
    await generatePDF(document.body);
});

// ── Using modules in HTML ─────────────────────────────────────────────────
// <script type="module" src="main.js"></script>
// type="module" enables:
//   - import / export syntax
//   - Deferred by default (loads after HTML parsed)
//   - Strict mode automatic
//   - Module scope — no global pollution
//   - CORS required — needs HTTP server, not file://

How It Works #

Step 1 — Static Analysis Before Execution #

Before any code runs, the JavaScript engine reads all import and export declarations and builds a module dependency graph. This allows bundlers (Vite, Webpack, Rollup) to eliminate unused exports (tree-shaking) and browsers to begin fetching dependent module files in parallel, improving startup performance.

Step 2 — Module Scope Eliminates Global Pollution #

In a regular <script>, top-level const x = 5 creates a global accessible as window.x. In a module, const x = 5 is scoped to that file — invisible to others unless explicitly exported. This eliminates the naming collisions that plagued pre-module JavaScript.

Step 3 — Modules Execute Once and Are Cached #

No matter how many files import from ./math.js, it is fetched, parsed, and executed exactly once. All importers receive the same module instance. Module-level state — a database connection, a configuration object, a singleton store — is naturally shared everywhere without any extra work.

Step 4 — Live Bindings vs CommonJS Copies #

ES module exports are live references to the original variables. If math.js exports let count = 0 and later does count++, all importers see the new value. CommonJS require() copies values at require time. Live bindings enable reactive patterns and are important to understand when module state changes.

Step 5 — Dynamic import() Enables Code Splitting #

import('./module.js') is a function call that returns a Promise resolving to the module’s export object. It can appear anywhere — inside event handlers, async functions, or conditionals. This lets bundlers split your application into smaller chunks loaded on demand, rather than one giant bundle loaded upfront.

Real-World Example: Plugin System with Dynamic Imports #

// plugin-manager.js

class PluginManager {
    #plugins = new Map();
    #hooks   = new Map();

    async register(name, path) {
        if (this.#plugins.has(name)) {
            console.warn(`Plugin "${name}" already registered`);
            return;
        }
        try {
            const module = await import(path);
            const plugin = module.default;

            if (typeof plugin?.install !== 'function') {
                throw new TypeError(`Plugin "${name}" must have an install() method`);
            }

            await plugin.install(this);
            this.#plugins.set(name, plugin);
            console.log(`Plugin "${name}" registered`);
        } catch (err) {
            console.error(`Failed to load plugin "${name}":`, err.message);
        }
    }

    addHook(event, fn) {
        if (!this.#hooks.has(event)) this.#hooks.set(event, []);
        this.#hooks.get(event).push(fn);
        return () => {
            const hooks = this.#hooks.get(event);
            const idx   = hooks.indexOf(fn);
            if (idx !== -1) hooks.splice(idx, 1);
        };
    }

    async applyHooks(event, data) {
        const fns  = this.#hooks.get(event) ?? [];
        let result = data;
        for (const fn of fns) result = await fn(result);
        return result;
    }

    has(name)    { return this.#plugins.has(name); }
    listPlugins() { return [...this.#plugins.keys()]; }
}

// ── plugins/markdown.js ────────────────────────────────────────────────────
export default {
    async install(manager) {
        manager.addHook('render', async content =>
            content
                .replace(/\*\*(.*?)\*\*/g, '<strong>$1</strong>')
                .replace(/_(.*?)_/g,       '<em>$1</em>')
        );
    }
};

// ── plugins/sanitize.js ────────────────────────────────────────────────────
export default {
    async install(manager) {
        // Runs first (registered first) — sanitize before rendering
        manager.addHook('render', async content =>
            content.replace(/<script.*?>.*?<\/script>/gis, '')
        );
    }
};

// ── Usage ──────────────────────────────────────────────────────────────────
const manager = new PluginManager();
await manager.register('sanitize', './plugins/sanitize.js');
await manager.register('markdown', './plugins/markdown.js');

const raw  = '**Hello** _World_ <script>evil()</script>';
const html = await manager.applyHooks('render', raw);
console.log(html);
// <strong>Hello</strong> <em>World</em>  (script removed)

console.log(manager.listPlugins());   // ['sanitize', 'markdown']

Common Mistakes #

Mistake 1 — Static import inside a block #

❌ Wrong — SyntaxError at parse time:

if (isDev) {
    import { debug } from './debug.js';   // SyntaxError
}

✅ Correct — use dynamic import for conditional loading:

if (isDev) {
    const { debug } = await import('./debug.js');
}

Mistake 2 — Wrong import syntax for default vs named #

❌ Wrong — curly braces for a default export:

import { User } from './user.js';   // SyntaxError if User is a default export

✅ Correct — no braces for default, braces for named:

import User        from './user.js';   // default export — no braces
import { add, PI } from './math.js';   // named exports — with braces

Mistake 3 — Trying to run module scripts via file:// #

❌ Wrong — browsers block module imports over file:// due to CORS:

// Opening index.html directly as a file — modules will fail with CORS error

✅ Correct — always serve via HTTP, even locally:

// npx serve .         — simple static server
// npx vite            — full dev server with HMR
// python -m http.server 3000  — Python quick server

▶ Try It Yourself

Quick Reference #