intermediate30 minby DevFox

Module Resolution, ESM, and CJS

Why an import that looks correct fails at runtime: the two module systems, resolution modes, file extensions, and reading the error instead of guessing at config.

TypeScript
Tooling

text

Error [ERR_MODULE_NOT_FOUND]: Cannot find module
'/app/dist/captions' imported from /app/dist/main.js

The file exists. The editor resolves the import. tsc --noEmit passes. It fails only when you run it, which is the worst error class in this language — the checker satisfied and the program broken.

There are two module systems here, several resolution strategies, and a compiler that emits for one while your runtime expects another. By the end of this lesson you will be able to read any of these errors and know which of four settings caused it.

Two systems

CommonJS came first, in Node:

javascript

const { makeCaption } = require("./captions");
module.exports = { makeCaption };

ES Modules are the standard, used by browsers and now by Node:

typescript

import { makeCaption } from "./captions.js";
export { makeCaption };

Three differences produce every problem in this lesson.

CommonJS

Resolved while the program runs.

require runs at the moment it is reached, so the path can be computed.

It guesses extensions — ./captions finds captions.js, then captions/index.js. And there is no top-level await.

ES Modules

Resolved before any code runs.

Which is what lets a bundler see the whole graph and remove the exports nobody imports.

Nothing is guessed: the path must be exact, extension included. Top-level await works.

Everything else in this lesson is a consequence of one of these three rows

Which one a file is

Node decides per file, from two things:

.mjs — always ESM
.cjs — always CommonJS
.js with "type": "module" nearby — ESM
"Nearby" means the closest package.json walking up from the file.
.js with anything else — CommonJS
Including no package.json at all, and including the case where you meant to add the field and did not.

Checked in this order — the extension wins outright, and only a plain .js has to ask

And the TypeScript equivalents: .mts is ESM, .cts is CommonJS, .ts follows the same package.json rule.

So the first question for any resolution error is: what does the nearest package.json say? A missing "type": "module" means every .js file in that tree is CommonJS, whatever the import syntax you wrote in TypeScript.

The extension that looks wrong

Bad — an extensionless import in an ESM project.

Good — the output extension.

You wrote captions.ts and import captions.js, which reads like a mistake and is correct. Import paths refer to what exists after compilation, and the compiler emits .js. Your editor resolves ./captions.js back to captions.ts.

The first version compiles to require("./captions") under CommonJS and works, or to import ... from "./captions" under ESM and fails at runtime — because Node's ESM resolver does not guess extensions. The checker never objects, because it resolves paths using its own strategy rather than the runtime's.

Whether you need the extension depends on one setting:

The four settings

module is what to emit — require calls or import statements.

moduleResolution is how to find files, and it must match what will actually run.

target is the language level of the output, unrelated to modules despite being adjacent in every config.

verbatimModuleSyntax stops the compiler guessing whether an import can be elided, and requires import type where it applies.

Two combinations cover nearly everything:

NodeNext reads package.json and follows Node's real rules — which is why it insists on extensions, and why it is the honest choice when Node runs your output. Bundler matches what bundlers do, which is more forgiving.

The obsolete value is "moduleResolution": "Node", which implements the CommonJS algorithm and does not understand the exports field. If you inherit a project with it and imports behave strangely, that is the first thing to change.

Importing CommonJS from ESM

Most of the ecosystem is still CommonJS, and mixing directions is where the remaining confusion lives.

ESM importing CommonJS works, with a caveat:

Node analyses the CommonJS file to find named exports, and the analysis is static — a module that assigns exports conditionally defeats it. When a named import fails from a CommonJS package, import the default and destructure:

esModuleInterop: true makes the TypeScript side of this work as expected, and it is on by default in modern configs.

CommonJS importing ESM does not work with require — ESM is asynchronous and require is not. Use a dynamic import:

Dynamic import() returns a promise and works from both systems, which makes it the escape hatch for this and for loading something conditionally.

What exports actually controls

A modern package declares its entry points explicitly:

Two things follow that surprise people.

exports is a boundary. Anything not listed cannot be imported, even if the file is in the published package. import "photo-tools/dist/internal.js" fails — which is a feature, since it lets you reorganise internals without breaking anyone.

types must come first in each condition block. Resolution takes the first match, so a types entry after import is never reached, and consumers get no types with no explanation.

If a package you depend on has no exports and resolution is strange, that is the older main/module world, and moduleResolution: "Node" is what reads it.

Reading the error

Four messages and what each means:

That last distinction is worth internalising. The first three are runtime failures where the checker was happy; the fourth is the checker, and the program may run fine.

A cheat sheet to keep

Where to go next

You can now diagnose an import that passes the checker and fails at runtime, which is otherwise an hour of guessing. The single most useful fact is that tsc resolves paths with its own strategy — so matching moduleResolution to what actually runs your code is what makes the two agree.

Next is Project Structure and References, which scales this up. Once a codebase has several packages, the questions become how to check them without rechecking everything, and how to stop one part importing another it should not.

Before you move on, look at your tsconfig.json and your package.json together. Check whether moduleResolution matches how the code actually runs, and whether "type" is set. Those two lines explain most import errors people spend an afternoon on.