Load, link, evaluate

Three steps: load, link, evaluate

A module is a JavaScript file that shares values with export and uses values from other files with import. The browser does not run a module the moment it sees it. First it gets every file ready. Only then does any code run.

The program that runs your JavaScript is called the host. It is the browser, or Node on a server.

This lesson comes after the browser security model. Those browser rules decide whether a file may be downloaded at all. The steps in this lesson start after that. Node uses the same three steps, but it has its own rules for finding files.

Two more words you will see all through this lesson:

• The module graph is the map of which file imports which.
• The entry module is the file you start from, such as main.js.

Loading starts at the entry module. But the files it imports usually run before it does. That explains many surprising logs in real apps.

The record for one module

When the engine reads a module file, it writes down notes about it. The spec, the official rule book for JavaScript, calls these notes a Source Text Module Record. In this lesson we just say module record. A module record keeps:

• which files this module imports from,
• which names it imports,
• which names it exports,
• which step it has reached: unlinked, linking, linked, evaluating, or evaluated.

1export let count = 0;2 3export function add() {4  count += 1;5}

Line 1 exports a variable named count. It starts at 0. Line 3 exports a function named add. The engine can list both exports just by reading the file. It does not need to run add to learn its name.

1import { count, add } from "./cart.js";2 3console.log(count);4add();5console.log(count);

Line 1 asks ./cart.js for two of its exports: count and add. Lines 3 to 5 are ordinary code, so they wait until every file is ready. Then they print 0 and then 1.

Your code can't see a module record. It is just a useful name. It helps you keep two things apart: what a module contains, and running its code. For example:

• A typing mistake in the file, called a syntax error, stops the record from being made at all.
• Importing a name that the other file doesn't export stops linking.

Step 1: loading the files

Loading means finding, downloading, and reading every module the entry module needs. Reading a file to understand its structure is called parsing. Start from main.js. The host sees that it asks for ./cart.js. It works out the full address of that file, downloads it if needed, and parses it into another module record.

1import { count } from "./cart.js";2console.log(count);

Line 1 is enough to add cart.js to the graph. Line 2 does not run while files are still being found. It runs later, in step 3, after linking has connected count to the real export.

Loading repeats itself. Each new file can import more files, and those get loaded too. If two files import the same file, the host loads it only once. Each module gets one record in the graph, so a shared file is linked once and run once.

Step 2: linking imports to exports

Linking connects each import to the export it asks for. In main.js, the imported name count gets connected to the exported count in cart.js. A name connected to a value like this is called a binding. Linking does not copy the number into a new variable.

1import { count } from "./cart.js";2 3console.log(count);

Line 1 asks for an export named exactly count. Line 3 reads it. If cart.js had no export called count, linking would fail with an error. You would not quietly get undefined.

This early error is useful. A file can be read without problems and still fail to link, because an import name is wrong. When linking fails, no code in the graph runs at all. You never get half a program.

Each row of this table is one step. Read across to see what the step does and what hasn't happened yet.

An import is not a copy

An imported name is a live binding. It always reads the value the exporting file has right now. That is different from copying a number into a new variable. The exporting file owns the variable. Files that import it can read it, but they can't give it a new value.

1import { count, add } from "./cart.js";2 3console.log(count);4add();5console.log(count);

Line 3 prints 0, because cart.js set count to 0. Line 4 calls add, a function inside cart.js. That function changes the same count. So line 5 prints 1, not an old copy of 0.

The step-through below uses a small stand-in for cart.js: a function called createCartModule that keeps count in a private variable. Reading cart.count calls a getter, a small function that hands back the current count. The stand-in shows the same change, one step at a time.

1const cart = createCartModule();Run2 3console.log(cart.count);4cart.add();5console.log(cart.count);

The step-through replays the stand-in code. It does not pause the real JavaScript engine.

Step 3: which file runs first

Evaluation runs the code in each module. A module runs only after the modules it imports have run. So imported files run before the files that import them.

1// shared.js2console.log("shared");3 4// a.js5import "./shared.js";6console.log("a");7 8// b.js9console.log("b");10 11// main.js12import "./a.js";13import "./b.js";14console.log("main");

Here main.js imports a.js and b.js, and a.js imports shared.js. The logs come out as shared, a, b, and main. Each file finishes before the file that imports it logs anything.

You can work out this order by hand with three rules:

1. Start at the entry module.
2. Before you write down a module, go into each of its imports, in order, and write those down first.
3. Never write down the same module twice.

Programmers call this a depth-first, post-order walk. Depth-first means you follow one import all the way down before you start the next one. Post-order means a module is written down after its imports.

1const graph = {2  "main.js": ["a.js", "b.js"],3  "a.js": ["shared.js"],4  "b.js": [],5  "shared.js": [],6};7 8function evaluationOrder(graph, entry) {9  const visited = new Set();10  const order = [];11  function visit(name) {12    if (visited.has(name)) return;13    visited.add(name);14    for (const dependency of graph[name] ?? []) visit(dependency);15    order.push(name);16  }17  visit(entry);18  return order;19}20 21console.log(evaluationOrder(graph, "main.js").join(", "));

This program follows those rules. It uses a Set, a list that holds each value at most once.

• Line 9 makes the visited set, which remembers the modules already seen.
• Line 12 stops if a module was seen before.
• Line 14 visits every import first.
• Only then does line 15 add the current module to order.
• Line 21 prints shared.js, a.js, b.js, main.js.

This is a small model for learning, not the engine's real code.

1const graph = {Run2  "main.js": ["a.js", "b.js"],3  "a.js": ["shared.js"],4  "b.js": [],5  "shared.js": [],6};7 8function evaluationOrder(graph, entry) {9  const visited = new Set();10  const order = [];11  function visit(name) {12    if (visited.has(name)) return;13    visited.add(name);14    for (const dependency of graph[name] ?? []) visit(dependency);15    order.push(name);16  }17  visit(entry);18  return order;19}20 21console.log(evaluationOrder(graph, "main.js").join(", "));

Change one import

Change one import and watch the order change. In the playground, remove only the import from a.js to shared.js. Now nothing imports shared.js, so main.js can't reach it. It drops out of the run order.

1const graph = {2  "main.js": ["a.js", "b.js"],3  "a.js": ["shared.js"],4  "b.js": [],5  "shared.js": [],6};7 8function evaluationOrder(graph, entry) {9  const visited = new Set();10  const order = [];11  function visit(name) {12    if (visited.has(name)) return;13    visited.add(name);14    for (const dependency of graph[name] ?? []) visit(dependency);15    order.push(name);16  }17  visit(entry);18  return order;19}20 21console.log(evaluationOrder(graph, "main.js").join(", "));

Reset puts the import back. The rule to remember: not every file in a folder runs. Only modules that the entry module can reach through imports are loaded and run.

One object with every export

import * as cart from "./cart.js" gives you one object, cart, that holds every export of cart.js. This object is called a module namespace object. Its values are live, like any import. But the importing file can't give them new values.

1// cart.js exports count and add.2import * as cart from "./cart.js";3 4console.log(Object.keys(cart).join(","));5console.log(cart[Symbol.toStringTag]);6console.log(cart.count);7cart.add();8console.log(cart.count);

• Line 2 makes the object named cart.
• Line 4 lists its property names with Object.keys. It prints add,count, because the names come out in alphabetical order.
• Line 5 reads a special built-in key, Symbol.toStringTag, which holds a short type name. Here it prints Module.
• Lines 6 to 8 show the live value: count goes from 0 to 1.

Module code always runs in strict mode, JavaScript's stricter set of rules. In strict mode, cart.count = 2 throws a TypeError, the error for using a value the wrong way. This protects the exporting file. cart.js can still change its own let count. Other files can only read it.

Each row of this table is a way to reach values. Read across to see what you get and when to use it.

How this helps in real apps

A feature file should import only the shared values it needs. A checkout page can import add and count from a cart module. It doesn't need to know how the cart keeps its data: in a simple variable, in a store, or on a server.

1import { add, count } from "./cart.js";2 3add();4console.log(count);

Line 1 imports the two exports by name. Line 3 changes the cart through its own add function. Line 4 reads the current count. If the cart starts at 0, as in this lesson, it prints 1.

The three steps also help you find bugs. Ask which step failed:

• A wrong file address or a network problem happens during loading.
• An error about a missing export happens during linking.
• An error thrown by code at the top level of a file happens during evaluation.

Knowing the step tells you where to look.

Common module mistakes

• “An import gets a copy.” An imported name is a live binding. It reads the exporting file's current value.
• “Loading runs code.” Loading only finds and reads the files. The code runs later, during evaluation.
• “Imports run top to bottom, like the lines in my file.” Imported files run before the files that import them. The module graph decides the order.
• “import * as gives a plain object.” It gives a special module object. You can read its live values, but you can't assign to them.
• “Each import runs a shared file again.” A file runs only once in a graph, no matter how many files import it.

Each row of this table is a word from this lesson. Read across to see what it means and what it does not mean.

These differences matter even more in the next lesson. There, two modules import each other. That is called a cycle. To follow a cycle, you need to know exactly which names are linked before either file finishes running.

Practice exercises

let count = 0;
function add() { count += 1; }
console.log(count);
add();
console.log(count);

const graph = { main: ["a", "b"], a: ["shared"], b: [], shared: [] };
const visited = new Set();
const order = [];
function visit(name) {
  if (visited.has(name)) return;
  visited.add(name);
  for (const dependency of graph[name]) visit(dependency);
  order.push(name);
}
visit("main");
console.log(order.join(","));

Check your understanding

For each question, first name the step: load, link, or evaluate. Trace the module graph only when a question asks about order. For a question about an imported value, ask two things: which file owns the value, and which file only reads it.

Key takeaways

• A module record is the engine's notes about one module file: its imports, its exports, and which step it has reached.
• Loading finds and reads every file the entry module needs. Linking connects each import to its export. Evaluation runs the code.
• An imported name is a live binding. When the exporting file changes the value, every file that imports it reads the new value.
• Imported files run before the files that import them. Each module runs only once.
• import * as gives a module namespace object. You can read its live values, but you can't assign to them. Its tag is Module.
• When something goes wrong, first ask which step failed: loading, linking, or evaluation.

Next lesson: circular dependencies, where two modules import each other. You will use the same module records, live bindings, and run order to see what happens.