TS2307 — module path resolution is not runtime loading

Root cause

TS2307 says the compiler cannot locate an imported module or matching type declarations under its configured resolution rules. A wrong relative path, incorrect filename casing, a missing dependency, mismatched ESM/CommonJS settings, an unresolved alias or missing declaration package can all cause it. Creating an empty d.ts declaration that says everything is any may quiet the compiler but does not make missing JavaScript code exist at runtime.

Reliable fix

For modern Node ESM, use module and moduleResolution set to NodeNext, a package.json with type module, and relative TypeScript imports written using the emitted .js suffix. Source file math.ts is resolved from ./math.js by the compiler and becomes a real dist/math.js file in the output directory. This exercise requires no downloaded packages or path aliases.

Verified TypeScript example

These are two separate source files:

// math.ts
export function sum(a: number, b: number): number { return a + b; }

// main.ts (separate file)
import {sum} from './math.js';
if (sum(2, 3) !== 5) throw Error();
console.log('PASS TS2307');

Why it works

The source illustration consists of two separate .ts files, not a single file containing two export and import declarations. Use tsconfig.json with strict:true, target ES2022 and outDir dist, and include both source files. The runtime then resolves the emitted .js import without a loader or bundler. NodeNext rules depend on package type; other environments may use different resolution modes.

Reproduction and build commands

Create package.json containing {"private":true,"type":"module"} and tsconfig.json containing {"compilerOptions":{"target":"ES2022","module":"NodeNext","moduleResolution":"NodeNext","strict":true,"outDir":"dist"},"include":["main.ts","math.ts"]}. Run tsc -p tsconfig.json && node dist/main.js and expect PASS. For a controlled TS2307, change import to ./missing.js and run tsc --noEmit -p tsconfig.json before restoring it.

Diagnostics to practice

Investigate case-sensitive paths on Linux versus case-insensitive developer filesystems. Run tsc --traceResolution -p tsconfig.json and identify the attempted candidate paths. If using a tsconfig paths alias, explain that a plain Node runtime does not automatically understand it; a bundler, loader or relative emitted imports must implement it.

Reference: https://www.typescriptlang.org/docs/handbook/modules/reference.html