JavaScript Modules & Scope Practice

ES modules and scope rules work together:

• Modules control what's shared between files
• Scope controls what's visible within a file

Master both and you'll avoid the most common JavaScript structural bugs.

// Single main thing → default
export default function Button() { ... }
import Button from "./Button.js";

// Multiple utilities → named
export const add = (a, b) => a + b;
export const subtract = (a, b) => a - b;
import { add, subtract } from "./math.js";

Why many teams prefer named exports:

• Import statements are explicit (you see what's imported)
• Renaming is consistent (import { add as sum } vs mystery defaults)
• Better IDE autocomplete and refactoring support

This surprises most developers:

// counter.js
export let count = 0;
export function increment() { count++; }

// main.js
import { count, increment } from "./counter.js";
console.log(count);  // 0
increment();
console.log(count);  // 1 (it updated!)

Static imports create read-only live bindings:

• The binding updates when the exporting module changes it
• You cannot reassign the import (count = 5 throws)

This enables circular dependencies to sometimes work, but it's also why they can fail mysteriously.

Static imports are hoisted and evaluated at load time. Dynamic import() is:

• Evaluated when the line executes
• Returns a Promise
• Works in non-module contexts (scripts, CommonJS)

// Conditional loading
if (needsChart) {
  const { Chart } = await import("./chart.js");
  new Chart(data);
}

// Code splitting
const routes = {
  "/dashboard": () => import("./pages/Dashboard.js"),
  "/settings": () => import("./pages/Settings.js"),
};

Use dynamic import when:

• You want code splitting (load on demand)
• Loading is conditional
• You're in a non-module context

Re-exports let you aggregate multiple modules into a single entry point:

// utils/index.js (barrel file)
export { add, subtract } from "./math.js";
export { formatDate } from "./date.js";
export { default as logger } from "./logger.js";

// Consumer imports from one place
import { add, formatDate, logger } from "./utils";

Re-export patterns:

When to use barrel files:

• Public API boundaries (expose clean interface)
• Grouping related utilities

Barrel files act as a Facade, presenting a simplified public API that hides the internal module structure from consumers.

When to avoid:

• Internal code (adds indirection)
• When tree-shaking matters (bundlers may struggle with export *)

ES modules support await at the top level. No wrapping async function needed:

// config.js
const response = await fetch("/api/config");
export const config = await response.json();

// main.js
import { config } from "./config.js";
// config is already resolved when this runs
console.log(config.apiUrl);

How it works:

• The module pauses at the await until the Promise resolves
• Any module that imports it also waits
• Creates a dependency chain for async initialization

Use cases:

• Loading configuration at startup
• Initializing database connections
• Conditional module loading based on async checks

Caution: Top-level await can slow down your app if overused. Every awaited module blocks its importers.

Unlike classic <script> tags, ES modules have their own scope:

// script tag (pollutes global)
<script>
  var name = "Alice";  // window.name = "Alice"
</script>

// ES module (isolated)
<script type="module">
  const name = "Alice";  // NOT on window
  // window.name is undefined
</script>

Why this matters:

• No accidental overwrites between scripts
• No naming collisions with libraries
• Explicit exports are the only way to share

If you need to expose something globally (rare), do it explicitly:

// Explicit global (avoid unless necessary)
window.myApp = { version: "1.0.0" };

Import declarations are hoisted, but this is different from var hoisting:

// This works because imports are hoisted
console.log(add(2, 3));  // 5
import { add } from "./math.js";

// But this is still bad style! Put imports at the top.

Key differences from var hoisting:

Why imports-at-top matters:

• Module side effects run when first imported, so order becomes implicit if imports are scattered
• Readability: imports at top show dependencies at a glance
• Some tools/linters require it

The TDZ is the region between entering a scope and the variable's declaration:

{
  // TDZ for `x` starts here
  console.log(x);  // ReferenceError: Cannot access 'x' before initialization
  let x = 10;      // TDZ ends here
}

Why TDZ exists: It catches bugs. Accessing a variable before declaration is almost always an error. For a quick reference of modern scope and module syntax alongside other ES6+ features, see the ES6 features cheat sheet.

What has TDZ: let, const, class

What doesn't: var (hoists as undefined), function declarations (fully hoisted)

// var hoists as undefined (no TDZ)
console.log(a);  // undefined
var a = 1;

// let/const have TDZ
console.log(b);  // ReferenceError
let b = 2;

// function declarations are fully hoisted
greet();  // Works!
function greet() { console.log("Hi"); }

Do you need to reassign it?
├── No → const
└── Yes → let

Never use var (unless legacy code requires it)

Why avoid var:

• Function-scoped, not block-scoped (leaks out of if/for blocks)
• Hoists as undefined (masks bugs)
• Can be redeclared (more bugs)

// var leaks out of blocks
if (true) {
  var leaked = "oops";
}
console.log(leaked);  // "oops" (still accessible!)

// let/const are block-scoped
if (true) {
  let contained = "safe";
}
console.log(contained);  // ReferenceError

Circular imports can work with ES modules, but they can also produce mysterious errors:

// a.js
import { b } from "./b.js";
export const a = "A";
console.log(b);  // Works if b is initialized

// b.js
import { a } from "./a.js";
export const b = "B";
console.log(a);  // ReferenceError! a isn't initialized yet

Why it fails: When b.js runs, a.js is still being evaluated. a exists (live binding) but hasn't been initialized yet (TDZ).

Fixes:

1. Move shared code to a third module (both import from it)
2. Use function calls instead of top-level access (delay evaluation)
3. Merge the modules if they're tightly coupled

// Fix: use a function to delay access
// b.js
import { getA } from "./a.js";
export const b = "B";
console.log(getA());  // Works, called after both modules load

// a.js
export const a = "A";
export const getA = () => a;

Generators produce values on demand:

function* range(start, end) {
  for (let i = start; i < end; i++) {
    yield i;
  }
}

// Only generates values as needed
for (const n of range(0, 1000000)) {
  if (n > 5) break;  // Stops early, doesn't generate all million
}

Generator use cases:

• Lazy sequences (infinite or expensive to compute)
• Custom iterators (see functions for how closures and generators relate)
• State machines

Key syntax:

• function* declares a generator
• yield pauses and returns a value
• Generators return an iterator

Node.js has two module systems. To use ES modules:

Option 1: Set package type

// package.json
{ "type": "module" }

Option 2: Use file extensions

• .mjs = ES module
• .cjs = CommonJS

Common pitfall: Mixing ESM and CommonJS requires care:

// ESM can import CommonJS
import pkg from "./commonjs-package.cjs";

// CommonJS cannot use import (use dynamic import or require)
const pkg = require("./commonjs-package.cjs");

• MDN: JavaScript modules
• MDN: import
• MDN: export
• MDN: Top-level await
• MDN: let
• MDN: Temporal dead zone
• MDN: function*
• Node.js: Modules