Circular dependencies

Two modules, one loop

A module is one JavaScript file that can share values with other files. A dependency is a file that another file imports. Sometimes two files import each other: a.js imports b.js, and b.js imports a.js. If you follow the imports, you come back to where you started. That is a circular dependency, also called an import cycle.

This lesson builds on Load, link, evaluate. That lesson showed three steps for modules:

• Load: find and read every file.
• Link: connect each import to its export.
• Evaluate: run the code, imported files first.

Linking happens before any code runs. So JavaScript can connect both imports in a loop before it knows if a file will read a value too early.

A cycle is not always a bug. It is a reason to ask one question: which values does each file read as soon as it runs, and which can wait until a function is called later? The answer is different for ES modules (files that use import and export) and CommonJS (files that use require, mostly in Node.js).

When you hunt for a cycle bug, start small:

1. Write down the first file that runs, the entry file.
2. Draw each import as an arrow.
3. Mark every value a file reads at the top level, outside any function. That code runs as soon as the file runs.

This small map often shows you the value that was read too early.

Cycles in ES modules

ES modules (ESM for short) are files that use import and export. Before any code runs, JavaScript loads every file and links each import to its export. Linking only connects names. It does not run any lines yet: no const gets its value, and no console.log prints. So an import can be connected before the other file has given it a value.

Here are three small files that make a loop.

1import { b } from "./b.js";2export const a = "A";3console.log("a sees", b);

• Line 1 imports b from b.js.
• Line 2 makes and exports a const named a, set to "A".
• Line 3 prints b.

This file looks fine on its own. But because of line 1, b.js runs first, before a.js gets to line 2.

1import { a } from "./a.js";2export const b = "B";3console.log("b sees", a);

• Line 1 imports a from a.js. This closes the loop.
• Line 2 sets b to "B". That works, because b belongs to this file.
• Line 3 reads a. This is the problem line. a.js is still waiting for b.js to finish, so a.js has not run its line 2 yet. The name a is connected, but it has no value.

1import "./a.js";

main.js is the entry file. It imports a.js. Then the files run in this order:

1. a.js imports b.js, so b.js runs first.
2. b.js sets b, then reads a on line 3.
3. JavaScript throws ReferenceError: Cannot access 'a' before initialization. A ReferenceError is the error for a name you can't use right now.

The run stops there. a.js never reaches its own console.log. This happens the same way every time. It is not about timing or luck.

TDZ errors across modules

A let or const name exists from the start of its scope, but it has no value until its line runs. The time in between is called the temporal dead zone, or TDZ. Reading the name during that time throws a ReferenceError.

In one file, you see this when you read a const above its line. A cycle makes the same thing happen across two files: b.js reads a while a is still in its TDZ.

ESM does not treat the import as missing. The name a is connected to a.js. JavaScript just refuses to read it yet. Why not give undefined instead? Because then your code would quietly carry on with a wrong value. An error tells you right away where the problem is.

1// b.js runs before a.js.Run2const b = "B";3let tdzMessage = "";4try { uninitialized("a"); } catch (error) { tdzMessage = error.message; }5console.log("b sees", tdzMessage);6 7function uninitialized(name) {8  throw new ReferenceError("Cannot access '" + name + "' before initialization");9}

The step-through uses a stand-in program, because a real cycle needs two files:

• Line 2 stands for b.js setting b.
• Line 4 stands for the early read of a. The helper uninitialized throws the same error that JavaScript throws.

The stand-in catches the error so you can see the message. The real files stop at the ReferenceError.

Don't "fix" this by changing every const to var. With var, the early read gives undefined instead of an error. The loop is still there, and now the bug is hidden. First ask: does this file really need the value as soon as it runs?

What works in a cycle

Some imports are safe in a cycle. The first safe kind is a function declaration: a function made with the function keyword, like function getA() { ... }. JavaScript sets up these functions during linking, before any line runs. So another file can call them even while the loop is still running.

1import { getB } from "./b.js";2export function getA() { return "A"; }3console.log("a sees", getB());

• Line 1 imports getB from b.js.
• Line 2 makes and exports the function getA. It returns "A".
• Line 3 calls getB() and prints a sees B.

1import { getA } from "./a.js";2export function getB() { return "B"; }3console.log("b sees", getA());

• Line 1 imports getA from a.js.
• Line 2 makes and exports the function getB. It returns "B".
• Line 3 calls getA(). a.js has not run yet, but getA was set up during linking. So the call works and prints b sees A.

1import "./a.js";

b.js runs first again. The whole run prints b sees A, then a sees B. The step-through below shows both functions ready before either file runs.

1function getA() { return "A"; }Run2function getB() { return "B"; }3 4console.log("b sees", getA());5console.log("a sees", getB());

The second safe kind is a later read: reading the import inside a function that runs after both files have finished. By then every value is set. Use this when the read really belongs to something that happens later, such as a click. Don't use it just to make an error go away.

1import { readB } from "./a.js";2console.log(readB());

This entry file uses two other files that import each other:

• a.js imports getB from b.js. It exports getA, which returns "A", and readB, which calls getB().
• b.js imports getA from a.js. It exports getB, which returns getA() + "B".

Neither file reads the other's values while it runs. They only make functions. Line 1 imports readB. Line 2 calls it after both files have finished. By then getA and getB are both set, so it prints AB.

CommonJS partial exports

CommonJS is the older module system in Node.js. Its files often end in .cjs. It has two tools:

• require("./b.cjs") runs another file right away and gives back what that file exports.
• module.exports is the object a file gives to anyone who requires it. It starts as an empty object, {}.

Node.js remembers each file's exports object as soon as the file starts running. So if b.cjs requires a.cjs while a.cjs is still running, b.cjs gets the object as it is right now. It does not wait for the finished one.

1const b = require("./b.cjs");2module.exports = { a: "A" };3console.log("a sees", b);

• Line 1 requires b.cjs. That file runs now, before line 2.
• Line 2 replaces module.exports with a new object, { a: "A" }.
• Line 3 prints b, after b.cjs has finished.

1const a = require("./a.cjs");2module.exports = { b: "B" };3console.log("b sees", a);

• Line 1 requires a.cjs. But a.cjs is still waiting on its line 1. Its exports object is still empty, so a gets {}.
• Line 2 sets this file's exports to { b: "B" }.
• Line 3 prints b sees {}.

Then b.cjs is done, and a.cjs carries on. It prints a sees { b: 'B' }. There is no error. You just get an object with nothing in it yet.

This code only runs in Node.js, so it has no Run button here. The lesson's tests run these two files in Node.js and check both printed lines.

1// a.cjs2exports.name = "A";3const b = require("./b.cjs");4module.exports = { name: "A", b };5 6// If b.cjs required a.cjs above, it still holds the first exports object.

• Line 2 adds name to the first exports object.
• Line 3 requires b.cjs. If b.cjs requires a.cjs back, it gets that first object: { name: "A" }.
• Line 4 replaces module.exports with a brand-new object. Files that require a.cjs after this get the new object.

Now there are two objects. b.cjs still holds the first one, so it never sees the new b property. To avoid this, add properties to exports instead of replacing module.exports.

ESM and CommonJS compared

Both module systems allow a cycle. But an early read goes wrong in different ways:

• In ESM, the name is connected but has no value yet. Reading it throws a ReferenceError.
• In CommonJS, you get the exports object as it is right now. It may still be empty.

Each row of this table is one case. Read across to see what is ready and what an early read does.

The table gives you two clues for finding bugs:

• An ESM error that says "before initialization" means a file read a let or const from another file too early, at its top level.
• A CommonJS log of an empty or half-filled object means a file required another file before that file had set its exports.

Neither one is random. Each follows its module system's rules. Once you know the system and the line that reads too early, choose a fix: move shared code to its own file, pass a function in, or read the value later.

Find a cycle in a graph

A module graph is the list of files and the arrows between them, where an arrow means "imports". You don't need to guess where a loop is. A short program can follow the arrows for you. It keeps a list of the files it is in the middle of visiting. If it reaches a file that is already on that list, it has gone round a loop.

1const graph = {2  "a.js": ["b.js"],3  "b.js": ["a.js"],4  "main.js": ["a.js"],5};6 7function findCycle(graph) {8  const visiting = new Set();9  const visited = new Set();10  function visit(name, path) {11    if (visiting.has(name)) return [...path, name];12    if (visited.has(name)) return null;13    visiting.add(name);14    for (const dependency of graph[name] ?? []) {15      const cycle = visit(dependency, [...path, name]);16      if (cycle) return cycle;17    }18    visiting.delete(name);19    visited.add(name);20    return null;21  }22  return Object.keys(graph).map((name) => visit(name, [])).find(Boolean) ?? null;23}24 25console.log(findCycle(graph).join(" -> "));

• Lines 1 to 5 write the graph as an object. Each file name lists the files it imports.
• Line 8 makes visiting, a Set (a list with no repeats) of the files on the current path.
• Line 10 starts visit, which walks from one file.
• Line 11 checks if the file is already on the path. If it is, that is a loop, so it returns the path.
• Lines 14 to 17 follow each import, one by one.
• Line 25 prints the loop it found: a.js -> b.js -> a.js.

This program is small on purpose. Real tools also handle things like package names and file endings. But the main idea is the same: a cycle is a path of imports that comes back to a file already on the path.

Break the dependency loop

The clearest fix is a third file. Find the code that both files need, and move it into its own file, such as shared.js. Then a.js and b.js both import shared.js, instead of importing each other.

1const graph = {2  "a.js": ["shared.js"],3  "b.js": ["shared.js"],4  "shared.js": [],5};6 7console.log(findCycle(graph));

• Lines 2 and 3: a.js and b.js each import only shared.js.
• Line 4: shared.js imports nothing, so no arrow leads back out of it.
• Line 7 runs findCycle from the last section. It prints null, which means "no loop found".

1const graph = {2  "a.js": ["b.js"],3  "b.js": ["a.js"],4  "main.js": ["a.js"],5};6 7function findCycle(graph) {8  const visiting = new Set();9  const visited = new Set();10  function visit(name, path) {11    if (visiting.has(name)) return [...path, name];12    if (visited.has(name)) return null;13    visiting.add(name);14    for (const dependency of graph[name] ?? []) {15      const cycle = visit(dependency, [...path, name]);16      if (cycle) return cycle;17    }18    visiting.delete(name);19    visited.add(name);20    return null;21  }22  return Object.keys(graph).map((name) => visit(name, [])).find(Boolean) ?? null;23}24 25console.log(findCycle(graph).join(" -> "));

There are two more ways to fix a loop:

• Pass it in. Give the function it needs as a parameter, instead of importing it. This is called dependency injection.
• Load it later. Read the value inside a function, or load the file with import() when a user action needs it. import() loads a file while the page runs and gives back a promise.

Loading later has a cost. Your code must wait for the promise, and it must handle the case where loading fails. So use it only when the file really is needed later, such as when the user opens an editor. Don't use it to hide a loop that a third file would fix.

After a fix, run the smallest entry file again. Check that no file reads from a file that is still running. Then keep a small test that checks the output, so a new import can't bring the loop back without anyone noticing.

Cycles in real applications

In a real app, a loop often grows by accident, one small import at a time. For example:

1. A screen file imports a store file, which holds the app's data.
2. The store imports a helper file.
3. The helper imports a constant from the screen file.

Now the screen imports itself through two other files. Each import looks harmless. You only notice the loop when one file reads another's value as soon as it runs.

Give each file one clear job, and keep imports pointing one way:

• A shared file holds types and simple helpers, like a price formatter.
• A service file sends requests to the server.
• A screen file imports both.

Imports should point from the screen down to the shared files, never back up to the screen.

When a build tool warns you about a circular dependency:

1. Check if the loop matters. A loop that only shares types is often harmless.
2. Look for values that a file reads as soon as it runs.

A harmless loop can still break later. All it takes is a new const at the top level that reads an imported value.

Common mistakes

• “Every cycle crashes.” A cycle works fine when no file reads another file's value too early.
• “An early ESM read gives undefined.” Reading an imported let or const before its line runs throws a ReferenceError.
• “CommonJS always gives the finished exports.” In a cycle, it can give the object as it is so far, even an empty one.
• “Changing const to var fixes it.” It only turns the error into undefined. The loop is still there.
• “import() is always the cleaner fix.” It only helps when the file really is needed later, such as after a click.

Each row of this table is an idea that is easy to mix up. Read across to see what it really means and what it does not mean.

Before you change any code, say which module system it is and which line reads too early. "In ESM, b.js reads a before a.js has set it" tells you what to fix. "Imports are weird" does not.

To review the TDZ rule in one file, read the temporal dead zone. To learn how the two module systems work together, see CommonJS and ESM.

Practice exercises

const graph = { a: ["b"], b: ["a"] };
console.log(findCycle(graph).join(" -> "));

function showOrder(formatter, order) {
  console.log(formatter(order));
}
showOrder((order) => order.id, { id: "tea" });

Check your understanding

For each question, first say which module system it is: ESM or CommonJS. Then ask: does the read happen while a file is still running, or after both files have finished?

Key takeaways

• A circular dependency is a loop of imports. ES modules connect every import in the loop before any file runs.
• Reading an imported let or const before its line runs throws a ReferenceError. The name is in its temporal dead zone (TDZ).
• Function declarations are safe in a cycle, and so are reads inside a function that runs after both files finish.
• In CommonJS, require can give back an exports object that is still empty. Replacing module.exports splits it into two objects.
• To break a loop, move the shared code to a third file, pass a function in, or load the file later when it really is needed later.

Coming next: Top-level await & async evaluation. There you will see a file use await at its top level. That lets a file pause in the middle of running, which changes the run order again.