JavaScript Modules (ES Modules)

Real applications span dozens of files. ES modules (the standard since 2015, usable natively in browsers) let you split code into files with explicit imports and exports — no globals, no load-order puzzles, real dependency graphs. This chapter covers the syntax, patterns and pitfalls.

Why modules?

• Namespaces — module scope replaces accidental globals; two files can both have helper().
• Explicit dependencies — a file states exactly what it uses.
• Maintainability — small, testable files instead of one 3,000-line script.
• Reuse — one utility file, imported by many features.
• Lazy loading — dynamic import() loads code only when needed.

Setup: type="module"

<script type="module" src="/js/app.js"></script>

Modules get, for free:

1. Deferred execution — runs after parsing (like defer).
2. Strict mode — sloppy-mode accidents (x = 5 creating globals) throw instead.
3. Isolated scope — nothing leaks to window.
4. CORS — module files are fetched with CORS rules (serve from the same origin or with proper headers).

Exporting

// utils.js
export const PI = 3.14159;

export function circleArea(r) {
  return PI * r * r;
}

export default function slugify(text) {          // one default export per file
  return text.toLowerCase().replace(/\s+/g, '-');
}

// also valid: named exports at the bottom
const clamp = (n, min, max) => Math.min(max, Math.max(min, n));
export { clamp };

Importing

// app.js
import slugify from './utils.js';               // default import (any name)
import { PI, circleArea } from './utils.js';     // named imports (exact names)
import { clamp as clampNum } from './utils.js';  // rename
import * as utils from './utils.js';             // namespace object

console.log(utils.PI, circleArea(2), slugify('Hello World'));
// → 3.14159 12.56636 hello-world

Default vs named — choosing

• Default — one primary thing per file: a component, the main class, a single function.
• Named — toolkits, constants, multiple helpers (preferred in utilities — imports stay self-documenting).
• Mixing is allowed, but most style guides lean named-first.

Relative paths are mandatory

import x from './helper.js';        // ✅ same directory (note the ./)
import y from '/js/helper.js';      // ✅ absolute from the site root
import z from 'helper.js';          // ❌ treated as a bare specifier (needs a bundler)

Extensions are required for browser-native modules (.js); bundlers like Vite may resolve extensionless imports for you.

Organising a real project

js/
├─ app.js            ← entry: wires everything together
├─ api.js            ← fetch helpers
├─ state.js          ← shared data
├─ ui/
│  ├─ header.js
│  └─ productList.js
└─ utils/
   ├─ format.js
   └─ debounce.js

// app.js — the entry point
import { fetchProducts } from './api.js';
import { renderList } from './ui/productList.js';
import { debounce } from './utils/debounce.js';

async function init() {
  const items = await fetchProducts();
  renderList(items);
}
init();

Side-effect and re-export patterns

export { formatDate } from './date.js';            // re-export
export { default as Chart } from './chart.js';     // re-export default under a name

import './analytics.js';                          // run for its side effect only

Dynamic import: load on demand

settingsBtn.addEventListener('click', async () => {
  const { openSettings } = await import('./ui/settings.js');
  openSettings();      // the code downloads only when the user opens settings
});

Dynamic imports return promises — perfect for code-splitting heavy features (charts, editors) so first load stays fast.

Circular imports

A imports B, B imports A — legal, but values may be partially initialised when accessed. Fix by breaking the cycle (move shared code to a third module). Treat cycles as a design smell.

Common mistakes

• Forgetting type="module" — a plain script using import throws SyntaxError.
• Missing ./ or the .js extension — the classic module 404.
• Expecting module variables on window — they are deliberately private; export them instead.
• Named vs default mix-ups — import { default as x } and import x from both fetch the default; named braces must match export names exactly.
• Module load order — modules are evaluated in dependency order automatically; no more hand-managed script tags.
• Importing everything into the entry file — pulls the whole graph; dynamic import() for optional features.

Practice checklist

1. Split a script into utils.js (named + default exports) and app.js; load with type="module".
2. Verify isolation: assign a variable without declaring it — confirm strict mode throws.
3. Lazy-load a secondary feature with dynamic import() and watch the Network tab.
4. Create a barrel file (index.js) re-exporting three utility modules.

Modules organise functions — classes organise domain models. Next: Classes & Object-Oriented JavaScript.