What a module is

Every program in this course so far has been a single stretch of code. That is fine while a program fits on a screen. Real projects do not. A working app is thousands of lines, and the moment you pass a few hundred, three problems arrive together and never leave.

The first is finding anything. You know the invoice total is calculated somewhere. Scrolling is not a search strategy. The second is name collisions: two parts of the program both want a variable called total, and in one shared file only one of them can have it. The third is the worst, and it is the one that actually costs money: nobody can tell which parts of the code are safe to change. If every function can be called from anywhere, then changing any function might break anything.

Modules are the answer to all three at once, and the answer is almost boringly simple: put related code in its own file, and make that file decide what the rest of the program is allowed to see.

Picture a workshop with the door locked and one small hatch in the wall. Inside there are tools, half-finished parts, notes to self, a kettle. None of it is visible from outside. The only things the outside world ever sees are the finished items the workshop chooses to push through the hatch, and it labels each one on the way out.

A module is that workshop, and a file is its walls. Everything you declare in the file is inside: helper functions, constants, the messy intermediate steps. Nothing leaves unless you put it through the hatch deliberately. The word for pushing something through the hatch is export, and the word for taking something from another workshop's hatch is import.

The value of the hatch is not secrecy for its own sake. It is that the hatch is a promise. What goes through it is what other files depend on, so it is what you have to keep working. Everything else you can rip out and rewrite this afternoon, because by construction nobody else can be relying on it.

In module 3 you met scope: a variable declared inside a function is invisible outside it. A module adds one more ring of exactly the same kind. Names declared at the top level of a module file belong to that module, not to the whole program, and they are not reachable from another file — not even by typing the right name — unless the module exports them.

This is worth sitting with, because it is the opposite of what a beginner usually assumes. Loading two files does not pour their variables into one shared pot. Each file keeps its own. That is why you can have a helper called format in a dozen different modules and never once collide.

So there are exactly two kinds of name in a module: the ones you export, which are its public surface and part of its contract, and everything else, which is private. There is no third category and no accidental middle ground. If you did not export it, it did not leave the room.

To publish, put the word export in front of a declaration — export function toFahrenheit(celsius) { ... } — or list names at the bottom of the file: export { toFahrenheit, isFreezing };. Both do the same job. The list form has the small advantage that a reader can see the whole public surface in one place.

To consume, write import { toFahrenheit } from "./temperature.js"; at the top of the file that needs it. The braces are not an object literal even though they look like one. They are a list of names you are picking out of that module's hatch, and each name has to match a name the other file actually exported. Spelling counts. Case counts.

The string after from is called the module specifier, and it comes in two flavours you will meet constantly. A relative specifier starts with ./ or ../ and points at a file by path, the way a link on a web page does; in the browser it includes the file extension. A bare specifier is a plain name like "date-fns", with no dots and no slashes at the front, and it does not mean a file in your project at all — it means a package, looked up in the node_modules folder. Lesson three of this module is about where those come from.

Here is the fact that surprises people, and the one that makes modules genuinely useful rather than just tidy: the code in a module file runs exactly once, the first time anything imports it. If twenty other files import it afterwards, they do not each get a fresh copy. They all get the same one that already exists.

So if a module creates a configuration object, a cache or a counter at its top level, that object is shared across the entire program. One instance, one state, one truth. This is a feature, and it is also the source of a whole family of confusing bugs: if module A changes something on that shared object, module B sees the change, even though B never asked anybody to change anything.

The mental model to keep: importing is not copying. It is being handed a reference to something that already exists. MDN puts the same point another way when it says imported bindings are live — the importing file sees the exporting file's current value, and cannot reassign it.

An import declaration may only appear at the top level of a module. Not inside an if, not inside a function, not halfway down. Try it and you get a syntax error before a single line executes.

That restriction can feel arbitrary until you see what it buys. Because every import sits at the top level and names its source with a plain string, a tool can read your files WITHOUT running them and work out the entire graph of what depends on what. That is what makes bundling, tree shaking and type checking possible at all, and it is why lesson five of this module keeps coming back to the word static.

It also means the imports are set up before the body of your file starts running. MDN describes import declarations as hoisted: the imported values are usable anywhere in the module, and the imported file's own top-level code has already run by the time yours starts. Putting your imports at the top is convention rather than a requirement, but the convention matches what actually happens.

The code runner on this page is a small sealed JavaScript engine with no file system, no network and no module loader. It cannot open a second file, because there is no second file. So an import line fails outright, and a program containing export confuses the runner about what your program's answer even was. This module is the one place in the course where the honest thing to say is: read this, do not run it.

What we can run is a model. A function that declares some private variables and then returns an object of functions gives you the same two-part shape a module has: a private inside and a published outside. You already know how to write one — it is the closure from module 3 wearing a different hat. Throughout these two lessons a function called createSomethingKit stands in for a file, and the object it returns stands in for that file's exports.

Where the model is accurate: what is inside stays inside, and only what you put on the returned object can be reached from outside. Where it stops being accurate: a real module body runs ONCE and everybody shares the result, whereas calling a factory twice builds two separate worlds that know nothing about each other. Keep that difference in view — the third worked example below shows both halves of it in nine lines.

"Cannot use import statement outside a module". The syntax is fine; the file was loaded as a plain script instead of a module. In a browser that means the script tag needs type="module"; in Node it means the nearest package.json needs "type": "module" or the file needs a .mjs extension. Lesson three comes back to this, because it is a project-configuration problem wearing an error message's clothing.

Forgetting the file extension. In the browser, "./temperature" is not the same request as "./temperature.js" and will simply 404. Some tools paper over this for you, which is worse rather than better, because the code then works in one place and not another.

Expecting a variable to work as a specifier. import { x } from someName is not valid: the source has to be a literal string, precisely so tools can read it without running it. When you genuinely need to choose a module at runtime there is a separate dynamic form, import(), which is a different tool for a different job and is not what this lesson is about.

Assuming an import copies the file's code into yours. It does not. It hands you a reference into a module that has already been evaluated, once, somewhere else. If you find yourself reasoning "but my file does not change it", check whether some other file shares the same instance.

A module is a file that keeps everything to itself except what it exports. Other files reach it with import, naming it either by relative path or as a bare package name. Its body runs once, and every importer shares that one evaluation; imports are references, not copies. Import declarations live at the top level and name their source with a literal string, which is what lets tools read your project without running it. Here, where there is no module loader, a factory function that returns an object of functions models the same private-inside, published-outside shape.