SESSION 031 — ES Modules

CONCEPTS.UNLOCKED

📦

ES Modules: import / export

JavaScript's native module system. Each file is a module with its own scope. export makes things available to other files. import brings them in.

{ }

Named Exports

export function grayscale() {...} → import { grayscale } from './filters.js'. Multiple named exports per file. Import only what you need.

⭐

Default Exports

export default class FilterManager → import FilterManager from './FilterManager.js'. One default per file. No curly braces on import.

🔒

Module Scope

Each file has its own scope — no more global variable conflicts. A variable in filters.js can't accidentally overwrite one in canvas.js. Isolation by default.

📂

Folder Structure Conventions

Group files by responsibility: scripts/, styles/, assets/. Within scripts/, split by concern: filters, canvas operations, UI, state, utilities. Every team follows conventions.

🔄

Circular Dependencies

A imports from B, B imports from A → trouble. Resolve by extracting shared code into a third module (e.g., utils.js) that both import from.

HANDS-ON.TASKS

Plan the Split

▶

src/scripts/
├── app.js       ← Entry point (thin orchestrator)
├── filters.js   ← All filter functions
├── canvas.js    ← Canvas operations (load, draw, export)
├── ui.js        ← DOM manipulation, event wiring
├── state.js     ← Settings, filter state, persistence
└── utils.js     ← clamp(), showToast(), generateExportName()

app.js becomes a thin orchestrator: it imports from each module and wires everything together. No business logic in app.js — just imports and initialization.

Extract Each Module with export

▶

// filters.js
export function grayscale(r, g, b) { ... }
export function brightness(r, g, b, amount) { ... }
export function clamp(value) { ... }

Move each group of related functions into its own file. Add export in front of every function that other modules need.

Import in app.js

▶

import { grayscale, brightness, contrast, invert }
  from './filters.js';
import { loadImageToCanvas, exportCanvas }
  from './canvas.js';
import { setupEventListeners }
  from './ui.js';
import { loadSettings, saveSettings }
  from './state.js';

Named imports use curly braces and must match the export names exactly. The paths are relative to the current file — './' means "same directory."

Update index.html

▶

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

type="module" tells the browser this is an ES Module. Without it, import/export won't work. Modules are automatically deferred (no need for defer attribute).

Verify & Resolve Circular Dependencies

▶

Verify nothing broke — all features work as before.

If you find circular dependencies (A imports B, B imports A), extract the shared code into utils.js or a new shared module.

Close the Ticket

▶

git switch -c refactor/PIXELCRAFT-019-modules
git add src/scripts/ src/index.html
git commit -m "Split app.js into ES Modules (PIXELCRAFT-019)"
git push origin refactor/PIXELCRAFT-019-modules
# PR → Review → Merge → Close ticket ✅

CS.DEEP-DIVE

Modularity and separation of concerns.

Arguably the most important principle in software engineering.

// Every well-designed system is modular:

CPUs          → separate ALU, cache,
                and control unit
Operating sys  → separate kernel,
                drivers, user space
The web itself → separate HTML, CSS, JS

// Modules let teams work in parallel,
// reduce bugs, and make systems maintainable.

// The mantra:
"Low coupling, high cohesion"
// Each module depends minimally on others
// but is internally focused.

REF.MATERIAL

ARTICLE

JavaScript Modules — MDN

Mozilla Developer Network

Complete guide to ES Modules: import/export syntax, default vs named, dynamic imports, and module loading behavior.

MODULESMDNESSENTIAL

VIDEO

JavaScript Modules in 100 Seconds — Fireship

Fireship

Rapid overview of ES Modules: why they exist, import/export syntax, and how they compare to CommonJS.

MODULESQUICK

VIDEO

ES Modules Explained — Web Dev Simplified

Web Dev Simplified

Practical walkthrough: splitting a project into modules, named vs default exports, and common mistakes.

MODULESPRACTICAL

ARTICLE

Modules Introduction — javascript.info

javascript.info

Interactive deep dive into modules: core features, module scope, import.meta, dynamic imports, and module-level execution.

MODULESINTERACTIVE

ARTICLE

Separation of Concerns — Wikipedia

Wikipedia

The foundational software engineering principle: each component addresses a separate concern. History, theory, and applications across all engineering.

ARCHITECTUREPRINCIPLESCS

ES MODULES