Why modules?

Why modules exist

Small programs fit in one file. Bigger programs don't. A shop's website might have:

• price math for the cart,
• a checkout screen,
• checks for the forms,
• code that counts what visitors click (called analytics),
• and tests.

Each part usually lives in its own file. In old-style JavaScript, every file puts its top-level names in one shared place. So one file can change a name that another file uses, by accident.

A module is a file that keeps its names private. The file chooses what to share:

• export marks a name that other files may use.
• import brings in a name that another file exported.

Before modules were part of JavaScript, people used other tricks for the same problem. You'll meet them in this lesson: IIFEs, namespaces, CommonJS, and AMD. Today JavaScript has its own built-in modules, called ES modules.

var count = 1;
var count = 2;
console.log(count);

Line 1 makes count and sets it to 1. Line 2 uses the same name again and sets it to 2. Line 3 prints 2. Now imagine lines 1 and 2 are in two different files, written by two different people. The second file changes the first file's count, and nobody notices. A module gives each file its own private count.

A classic script is a normal <script> tag without type="module". You can put several on one page. They run in order, top to bottom.

The problem is that all classic scripts share one global scope. The global scope is the outermost place where names live. Every script on the page can see it. Names act in two ways there:

• Top-level var and top-level function names also become properties of the global object. In a browser, the global object is window. So var count makes window.count.
• Top-level let, const, and class names are shared by every script too. But they don't become window properties.

The old var and the global object lesson covers this difference in more detail.

var cart = "tea";
let price = 3;
console.log(globalThis.cart);
console.log(globalThis.price);

globalThis is a name for the global object that works everywhere. In a browser, it is window.

• Line 1 makes cart with var, so globalThis.cart exists. Line 3 prints tea.
• Line 2 makes price with let. It is a global name too, but not a property. So line 4 prints undefined.

The lab below runs two real classic scripts inside an iframe, which is a small page inside this page. A sandbox setting stops that small page from touching this one. Both scripts pick the names count and format. Switch the order and see which script's version is left at the end.

1<script>2var count = 1;3function format() { return "cart:" + count; }4window.cartFeature = format();5</script>6<script>7var count = 99;8function format() { return "profile:" + count; }9window.profileFeature = format();10</script>11<script>12window.report = [cartFeature, profileFeature, format(), window.count];13</script>

This bug is hard to spot because each file looks fine on its own. The cart file says, "I need a count and a format." The profile file says the same thing. The page only breaks when both files load together. The order decides which version is left.

When a shared name has the wrong value, ask: "Which script wrote this name last?" In the browser's developer tools, the Network panel shows the order the scripts loaded. Then search the code for every place that writes that name. Renaming one variable may hide the bug for now. The real fix is to stop sharing the name.

Before JavaScript had modules, programmers often wrapped each feature in an IIFE. The letters stand for "immediately invoked function expression". It is a function that is called right where it is written.

A function has its own scope: names made inside it stay inside it. So an IIFE keeps its names private. Code outside can only get what the function returns, or what it puts on a public object.

(function () {
  const secret = "tea";
  console.log(secret);
}());

• The round bracket at the start of line 1 and the last one on line 4 wrap the whole thing. They make JavaScript read the function as an expression, a value that can be called on the spot.
• The () on line 4 calls the function right away.
• Line 2 makes secret inside the function. Line 3 prints tea.
• Code outside the function can't use the name secret.

globalThis.CartApp = (function () {
  const price = 3;
  return { price };
}());
console.log(globalThis.CartApp.price);

A namespace is one public object that holds everything a feature wants to share.

• Line 2 makes price inside the IIFE, so it is private.
• Line 3 returns a small object. { price } is short for { price: price }.
• Line 1 stores that object as globalThis.CartApp.
• Line 5 reads price through CartApp and prints 3.

The name CartApp itself is still global. If two teams both choose CartApp, they still clash.

1<script>2window.CartApp = (function () {3  var count = 1;4  function format() { return "cart:" + count; }5  return { feature: format() };6}());7</script>8<script>9window.ProfileApp = (function () {10  var count = 99;11  function format() { return "profile:" + count; }12  return { feature: format() };13}());14</script>

Namespaces were a big step forward. One public object made it clear what each feature shared: "the cart's public tools are in CartApp." But two problems were left:

• The namespace name itself is still a global name.
• You still have to put the script tags in the right order by hand.

The next tools, CommonJS and AMD, add a loader: code that finds each file and runs it when it is needed.

A namespace is still useful for a small old widget that must work without build tools. In a new app, use it only for a short time while you move code over. First move a feature behind one object. Then switch to real imports once the page can use modules.

CommonJS and AMD are two older module systems. You still see them in tools, libraries, and older code.

CommonJS was Node's first module system. It uses two names:

• require(id) loads another file and gives back what that file shares. It is synchronous: the next line waits until the file has loaded and run.
• module.exports is the object a file fills with the things it shares.

Waiting is fine on a server, where files sit on the local disk and load fast. Three parts make CommonJS work:

• a wrapper function around each file, so the file's names stay private,
• an exports object that collects what the file shares,
• and a cache: a store that remembers each file after its first load.

1const modules = {Run2  "./math": function (module) {3    module.exports.add = (a, b) => a + b;4  },5  "./cart": function (module, exports, require) {6    const math = require("./math");7    exports.total = (items) => items.reduce(math.add, 0);8  }9};10const cache = {};11function require(id) {12  if (cache[id]) return cache[id].exports;13  const module = { exports: {} };14  cache[id] = module;15  modules[id](module, module.exports, require);16  return module.exports;17}18const cart = require("./cart");19console.log(cart.total([2, 3]));

Step through the code above. On the first load, require runs ./cart and keeps it in the cache. Pick "Cached second load" to see the second require skip the file and give back the same object.

AMD stands for Asynchronous Module Definition. It was made for browsers, where files come over the network and can be slow. A popular AMD loader was called RequireJS. AMD code has the shape define(["dep"], factory):

• The array lists the files this module needs. These are its dependencies.
• The loader downloads them asynchronously: the page keeps running while they download.
• When they arrive, the loader calls the factory, a function that builds the module. It passes the dependencies in.

define(["./price"], function (price) {
  console.log(price);
});

Line 1 asks for ./price before the factory runs. The factory then gets it as the price parameter, and line 2 prints it. You can't run this snippet by itself: define only exists when an AMD loader, such as RequireJS, is on the page. You don't need to write AMD for a modern browser app. But you'll see it in older packages.

Don't mix up a module format with the place it runs. A bundler is a tool that joins many module files into a few files for the browser. CommonJS can run in a browser after a bundler rewrites it. But a plain browser page has no require of its own. Node and browsers also find files in different ways:

• Node looks up package names and files with its own rules.
• Browsers treat each import path as a URL (a web address), or look it up in an import map, a list that maps short names to URLs.

1define(["./math"], function (math) {2  return {3    total: function (items) {4      return items.reduce(math.add, 0);5    }6  };7});

ES modules are the standard module system built into JavaScript. They arrived in ES2015, and browsers and Node both support them now. An ES module follows these rules:

• It has its own top-level scope. Its names are private to the file.
• It always runs in strict mode, the safer set of JavaScript rules.
• It runs only once per URL, even if many files import it.
• It shares values only through export and import.

In a browser, you mark a module with <script type="module">. Module scripts are deferred by default: they wait until the browser has read all the HTML. A classic script without defer or async makes the browser stop reading the HTML while it runs.

<script type="module">
  import { total } from "./cart.js";
  console.log(total([2, 3]));
</script>

• Line 1 marks the script as a module.
• Line 2 imports total from cart.js.
• Line 3 calls total([2, 3]) and prints the result.

Anyone reading line 2 can see that this script needs cart.js. So can tools.

Imports are written at the top of a file and never change while it runs. So a bundler can see which exports nobody imports, and leave them out of the final files. This is called tree-shaking. It makes files smaller. It is a bundler feature; browsers don't need it to run modules.

1<script type="importmap">2{ "imports": { "cart": "data:text/javascript,..." } }3</script>4<script type="module">5import { count, total } from "cart";6window.moduleTop = typeof count;7console.log(total([2, 3]));8console.log(this === undefined);9</script>

Notice the change in thinking. Old scripts ask, "Which names are already on window?" Modules ask, "Which file exports the thing I need?" The next lessons build on this: named exports, default exports, re-exports, import maps, loading a module later with import(), and mixing CommonJS with ES modules.

Modules keep names private, but they don't make code safe. Imported code can still do anything the page can do. An exported object can still be changed by other files. So:

• keep secrets on a server,
• check data that comes from outside your code,
• and export only what other files need.

Global script, IIFE, CommonJS, AMD, or ES module?

Each pattern has a clue you can spot in the code:

• window, or a top-level var in a script tag: a classic global script.
• A function called right where it is written: an IIFE.
• require: CommonJS.
• define: AMD.
• import or export: an ES module.

The table compares the five patterns. Each row is one pattern: how it shares code, and what it costs you.

Now sort the snippets. If you miss one, read its explanation and look for the clue.

Where you’ll use this

In real front-end work, modules let you split code by job:

• One file does the cart math.
• Another file draws the checkout.
• Tests can import the math without drawing the page.
• A new teammate can see what a file needs by reading its first lines.

1// cart.js2// Export only the function that checkout needs.3export function total(items) {4  return items.reduce((sum, item) => sum + item.price, 0);5}6 7// checkout.js8import { total } from "./cart.js";9 10// Checkout uses total, but the math stays in cart.js.11export function renderCheckout(items) {12  return "Total: $" + total(items);13}

• Line 3 exports total from cart.js.
• Line 8 imports it into checkout.js.
• Line 11 exports renderCheckout, which uses total to build the text it shows.

A few tips for real projects:

• Make a module when some code has one clear job and only a few things to share.
• Keep helper functions unexported until another file really needs them.
• Import what you need. Don't hope that a global already exists.
• In old code, find out which pattern loads and shares the files before you rename anything.
• In a browser, an import path like ./cart.js is a URL, so the page usually needs a web server. Node has its own rules for package names and file endings.
• Imports written at the top let tools see which file needs which. That helps with caching and tree-shaking. A bundler is still optional.
• Don't move a two-line helper into its own file just to have more files. Split when it makes clear which file is in charge of the code, or when other files reuse it.
• Later you'll meet import(), which loads a module only when it is needed. Use it for big or optional features, so the first screen loads faster.

Common misconceptions

Key takeaways

• Classic scripts share one global scope. Top-level var and function names also show up on window.
• An IIFE keeps names private inside a function. It usually shares one namespace object.
• CommonJS uses require, which waits for the file, plus module.exports and a cache.
• AMD uses define([deps], factory) to load files without making the page wait.
• ES modules keep names private, always use strict mode, run once per URL, and share through import and export.

Up next: import & export. You'll learn named exports, default exports, re-exports, and live bindings (imports that always show the exporting file's current value).