At the close of the previous lesson the Nómada Tasks model was complete and protected: Task with its private state, Board with its minimal public API, ValidationError with its hierarchy. The problem is that all of it lives in a single js/app.js that is already past three hundred lines, mixed together with the constants, the sample backlog and the code that runs it. Splitting it into several files and loading them with <script> solves nothing: they all share the same global space, load order becomes an invisible dependency nobody has written down, and it only takes two files declaring const WEIGHTS for the application to fall over. In this lesson you will learn JavaScript's module system: explicit boundaries between files, with export to declare what is on offer and import to declare what is needed. By the end you will have reorganized the whole project into six real files, with a dependency graph you can draw.

1. The problem: global scope, order and invisible dependencies
2. export: named exports
3. import: bringing in what you need
4. Renaming with as and importing everything with * as
5. export default
6. Re-exporting: the barrel file
7. Own scope and single execution
8. <script type="module"> and what changes
9. Dynamic import() and module-level await
10. CommonJS: require and module.exports
11. Node and "type": "module"
12. Circular dependencies
13. Nómada Tasks, reorganized
14. Common Mistakes and Tips
15. Exercises
16. Conclusion

Suppose you split the big file into three and load them as you learned in Module 1:

This has three serious problems, and none of them gives a clear error message.

Problem 1: everything shares the same global scope. Every classic <script> runs its code in the global scope, so all top-level declarations live together in the same namespace.

Two files written by two different people, each one perfectly reasonable, and the application does not start. With var it would be even worse: there would be no error, the second would overwrite the first silently, and the effort calculation would come out NaN somewhere unexpected.

Problem 2: order matters and it is written nowhere. If somebody moves the <script> for task.js above the one for constants.js, the Task class will try to use WEIGHTS before it exists. The HTML becomes a critical configuration file nobody documents.

Problem 3: dependencies are invisible. Open task.js and tell me what it depends on. You cannot know without reading the whole thing and hunting for the identifiers it does not declare. There is no line saying "this file needs WEIGHTS and ValidationError".

The classic workaround, before modules existed, was the module pattern from 03-04: wrapping everything in a self-invoking function and hanging a single variable off the global object.

It works —it was best practice for years— but it still does not solve ordering or make dependencies explicit, and it only takes two libraries picking the same global name to be back at problem 1. Since ES2015, the language has shipped the solution.

A module is simply a .js file that uses export or import. Everything it declares is private to that file except what it exports explicitly.

There are two ways of writing the same thing. The first is putting export in front of each declaration, as above. The second is grouping them at the end of the file, which gives you a very convenient "table of contents":

Anything with a name can be exported: const, let, function, class. And it can be renamed in the export itself:

export and import declarations must be at the top level of the module, never inside an if, a loop or a function. The reason is that they are analyzed before anything runs: that lets the browser discover the file graph and download the files in parallel, and it is also what makes it possible to detect import errors without ever executing the program. For conditional importing there is dynamic import() (section 9).

At the other end, import declares what is needed and where it comes from.

The braces of import { … } are not destructuring, even though they look a lot like the ones in 04-07. It is a syntax of its own belonging to the module system: the names have to match the exported ones exactly, it takes no default values or nested patterns, and it is resolved before anything runs.

About the module path (the specifier), three rules that trip people up in the browser:

And the most important one: in the browser, the .js extension is mandatory. import { TODAY } from './util/dates' fails with a 404. Node in ESM mode requires it too. It is the number one mistake for people coming from other environments where it can be omitted.

If two modules export something with the same name, or if the original name clashes with a local variable, you rename it on import:

And if you want the whole module grouped under one name:

That dates is the module namespace object: it holds one property per export. It has two peculiarities: it is frozen (you cannot add to it or change it) and its properties are live bindings, not copies, something you will see in section 7.

Each module can have one default export, meant for when the file represents a single thing.

The difference from named exports:

They can be combined in the same file:

In this project we will use named exports in every file. It is not the only valid option —many teams use default for each module's main piece— but named exports have two practical advantages: the name is the same across the whole code base, which means searching for Board finds every use, and a typo shows up instantly instead of giving you undefined halfway through execution.

A module can re-export what it imports from others, without ever using it. It serves to offer a single entry point to a group of files.

Whoever consumes it sees a single module:

Barrels are convenient, but an honest warning is in order: importing from the barrel drags in the load of every file it re-exports, even if you only use one. With six files it is irrelevant; in large projects it is one of the typical reasons startup becomes slow, and its relationship with code splitting is covered in 09-05. For a project the size of Nómada Tasks, importing directly from each file is clearer.

Two properties of modules that solve exactly the problems in section 1.

Every module has its own scope. Nothing you declare is global, so two modules can declare const WEIGHTS without either one noticing. Problem 1 is gone.

A module runs only once, however many times it is imported. The first import loads and runs it; the rest receive the already-computed result. That makes every module a de facto singleton:

In the console, '⚙ counter.js is running' appears only once. The two modules share the same log because they share the same module instance. That property is extremely useful —a configuration module, a cache, a shared store— but it is worth keeping in mind: any state you put at module level is global to the whole application, with all the drawbacks that has for the tests in Module 8.

And a fine detail: imports are live bindings, not copies. If the source module reassigns an exported variable, whoever imported it sees the new value.

Imported variables are read-only from the importing module: only the owning module can change them. It is a form of encapsulation that fits perfectly with what you learned in 05-03.

For the browser to treat a file as a module you have to say so:

A single <script> for the whole application: the imports take care of the rest, and the browser discovers and downloads the complete graph. These are the differences from a classic script:

The implicit defer is good practical news: when you get to Module 6 and start looking for elements on the page, the HTML will already be fully built, with no need to wait for any event. And if you need the opposite —running as soon as it downloads, without waiting— there is <script type="module" async src="…">.

The last row is the one that causes the most headaches. Opening index.html by double-clicking does not work with modules:

The reason is security: modules are downloaded under the same rules as any network request, and the file:// protocol has no valid origin. The solution is the one you already met in 01-02: start a local server.

And then open http://localhost:8000, not the file path. From now on, all development on the project is done with a local server running.

Static imports go at the top of the file and are resolved before anything runs. When you need to load something conditionally or at a specific moment, there is the function form:

We focus here only on the syntax, because its main use —splitting the application into chunks that download on demand so it starts faster— belongs to 09-05, and because what it returns is a promise, an object you will study in depth in 05-06. Keep three differences in mind:

That await in the example is also unusual outside a function: in ES modules you are allowed to use await directly at the top level, something called top-level await.

When a module uses await at the top level, every module that imports it waits for it to finish before running. It is a convenient tool, but it has a real cost at application startup, so it is worth using with care. You will come back to it in 05-06, when await stops being a word that appears in passing.

Before ES modules existed, Node.js invented its own system, called CommonJS, and it is still everywhere. You are going to run into it constantly, so you need to recognize it.

Here the braces really are destructuring (04-07), because require returns an ordinary object. That is the underlying difference between the two systems:

The difference between "live binding" and "copy" has visible consequences:

With ESM, that same code would print 1. It is a classic source of confusion when migrating between systems.

Which to use today: ESM for everything new. It is the language standard, it works in the browser and in Node, and it allows the static analysis the tools in 09-05 depend on. You will see CommonJS in projects a few years old, in many configuration files and in old dependencies.

In the browser, type="module" on the tag decides the system. In Node it is decided by the folder's package.json:

With "type": "module", Node reads every .js in that project as an ES module. Without that line (or with "type": "commonjs"), it reads them as CommonJS. And if you need to mix, extensions win over the package.json:

With that in place you can already run the project from the terminal, which is very handy for testing the logic without opening a browser:

A frequent gotcha: in an ES module there is no require, __dirname or __filename. If you need them there are modern equivalents, but normally you will not miss them.

Two modules that import each other form a cycle. It is not a language error, but it usually ends in undefined at the worst possible moment.

What happens underneath is that one module starts running, hits the import, goes to the other, and that one comes back to the first —which has not finished running yet. With class, which has a temporal dead zone (05-02), the typical result is an error like Cannot access 'Task' before initialization.

A cycle is almost always a design signal: two modules that need each other are really one, or they are missing a third. The three usual ways out:

1. Extract what is common into a third module. If both need the constants and the errors, pull them out into model/errors.js and model/rules.js, and have both depend on those.
2. Invert the dependency. Let Board know about Task (it adds tasks), but let Task not know about Board. If a task needs something from the board, it should be passed in as a parameter.
3. Merge the two modules if they really are inseparable.

In Nómada Tasks we apply number 2, which is the one that produces a clean graph: the lower layers do not know about the upper ones.

Here is the whole project spread across its final modules. This is the structure every following module of the course will work on.

And its dependency graph:

Notice that every arrow points downwards: util/ and model/errors.js depend on nobody, model/task.js depends on them, model/board.js depends on the task, and app.js sits right at the top. There are no cycles, and every file declares in its first lines exactly what it depends on.

Now the files. First the leaves of the graph:

Now the model, which contains only what belongs to it:

Notice the import { isOverdue as dateOverdue }: the utility function and the class method have the same name, and as resolves the clash without renaming either of them. That is exactly what it exists for.

That createBacklog() as a function, instead of an already-built exported array, is a deliberate decision. Since modules run only once (section 7), a directly exported array would be the same one for the whole application, and a test that changed a task's status would contaminate the next one. By returning new instances on every call, each consumer has its own.

And finally the entry point, which no longer contains any logic: it just orchestrates.

Running it with node js/app.js (or opening index.html from the local server and looking at the console):

The same canonical numbers as always, now produced by six files with clear boundaries. And most importantly: if tomorrow the effort calculation has to change, you know exactly which file to open.

• Forgetting the .js extension in the specifier. from './util/dates' gives a 404 in the browser and an ERR_MODULE_NOT_FOUND in Node. The extension is mandatory.
• Opening the HTML by double-clicking. Modules do not work over file:// because of CORS. Always a local server.
• Confusing import { X } with destructuring. It takes no defaults, no renaming with :, no nested patterns; renaming is done with as.
• A misspelled name in a named import. It gives SyntaxError: The requested module does not provide an export named 'Boar'. It is a good error: it shows up at load time, not halfway through execution.
• Mixing export default and named exports without a criterion. Pick a convention per project and stick to it. In Nómada Tasks: always named.
• Putting an import inside an if or a function. It is a SyntaxError; that is what dynamic import() is for.
• Mutable state at module level. Since the module runs once, an export const cache = new Map() is global to the whole application. Sometimes that is exactly what you want; other times it is a headache in the Module 8 tests. Export factory functions when each consumer should have its own.
• Circular dependencies. If you see Cannot access 'X' before initialization, look for the cycle. The fix is almost never a trick: it is redesigning so dependencies point in one direction only.
• Barrels in large projects. An index.js that re-exports fifty files loads them all even if you use one. Convenient, but at a cost (09-05).
• Tip: order the imports in each file by layer —external libraries first, then project modules, then the nearest ones. It is the convention the tools in 08-02 apply, and it makes the file read like a statement of intent.

Exercise 1 — Spot the cycle. This project does not start. Draw the graph, identify the cycle and propose a reorganization with a new module.

Exercise 2 — A util/stats.js module. Create a module exporting mean(numbers), maxBy(objects, field) and groupBy(objects, field), plus a VERSION constant. None of the three may import anything from the model (they must work for any array of objects). Then write an app.js that imports it and calculates, over the canonical backlog: the mean number of hours of the open tasks, the task with the most hours, and the grouping by priority.

Exercise 3 — Shared counter. Create data/metrics.js exporting record(event) and report(), keeping the count in module state. Import it from model/task.js and from model/board.js, record an event on every status change, and show with a console trace that the two modules share the same counter. Then explain in two lines when that would be a problem.

Exercise 1

The cycle is direct: report.js → board.js → report.js.

The underlying cause is a layer inversion: Board is a model piece and should know nothing about how reports are formatted. The fix is not an import trick, but sorting out the responsibilities:

The resulting graph, cycle-free and with every arrow pointing the same way:

The general lesson: when a cycle appears, there is almost always a layer looking upwards. Here it was Board.print(), a presentation method in a model class.

Exercise 2

The constraint in the statement —that it must not import anything from the model— is the point of the exercise. mean, maxBy and groupBy work just as well with tasks, with residents or with room bookings, and that is why they live in util/ and depend on nobody: they are a leaf of the graph. A utility module that imports from the model stops being reusable and is the seed of the next cycle. Note as well that maxBy returns the first maximum in the event of a tie, because the comparison is strict (>).

Exercise 3

That the report adds up the calls made from two different modules proves that both received the same instance of metrics.js: the module was loaded and run once, and that Map is unique.

When is it a problem? When the shared state should be independent. In the Module 8 tests, each test would inherit the previous one's counts and would fail intermittently —hence why we exported reset(). And if the application showed two boards at once, the metrics of both would blend together with no way to separate them. The alternative is the same one we applied in createBacklog(): export a factory (createMetrics()) so each consumer has its own instance, and reserve module state for what really is global, such as the application's configuration.

The project has stopped being a file and become an architecture. The three problems from the beginning are solved by construction: every module has its own scope, so two files can declare WEIGHTS without either noticing; load order is worked out by the engine from the imports, not by the HTML; and dependencies are explicit, written in the first lines of each file, to the point where you can draw the graph and check at a glance that every arrow points downwards.

You have the complete syntax down. export in front of a declaration or grouped in a list at the end; import { a, b } with names that must match —it is not destructuring—; as to rename at either end, as you did with isOverdue as dateOverdue to resolve a real clash; import * as ns to bring in the whole namespace; export default for the "this file is a single thing" case, with its pros and cons against named exports; and re-exporting through barrels, convenient but with a loading cost worth knowing about. You know that a module runs only once and works like a singleton, that imports are read-only live bindings, and that this is why createBacklog() is a function and not an exported array.

On the environment side you have the full picture: <script type="module"> with its own scope, its permanent strict mode, its implicit defer —which will come in very handy in Module 6— and its requirement of a local server because of CORS; dynamic import() and module-level await as syntax you will pick up again in 05-06 and 09-05; CommonJS with require/module.exports so you recognize it when it turns up, with its table of differences against ESM —static versus dynamic resolution, live bindings versus copies, browser support or none—; and the "type": "module" in package.json that lets you run the project with node js/app.js. And you know how to diagnose a circular dependency: not as an import problem to be fixed with a trick, but as the symptom of a layer looking upwards.

Nómada Tasks now lives in model/task.js, model/board.js, model/errors.js, data/backlog.js, util/dates.js, util/format.js and js/app.js, and it still gives the same numbers as always: 48 h in total, 45 open, 1 overdue, effort 124, Iván on 25 h, Lucía on 14 and Marta on 6. With one important difference: that data/backlog.js is currently a hand-written array, and everybody knows that in the real application the data will come from somewhere —a file, a server— and will take time to arrive. A single-threaded language cannot sit there waiting with its arms folded while that happens, because while it waits the entire interface freezes. How to program a wait without blocking anything is the course's other great leap, and it starts in Asynchronous JavaScript: Callbacks.