TypeScript Reference ยท tsconfig: Language, Modules and Emit Options
TypeScript moduleResolution option
Reference for the moduleResolution option: how TypeScript turns an import specifier into a file, and the differences between nodenext, bundler and legacy node.
moduleResolution is the algorithm the compiler uses to turn an import string like "./util.js" or "lodash" into a file with types. It must predict what the real runtime or bundler will do; if the two disagree, the compiler accepts imports that fail at runtime, or rejects ones that work.
Two modern strategies cover almost everything: nodenext for code run by Node itself, and bundler for code processed by a bundler. The older node10 (spelled node in old configs) ignores package.json exports and is deprecated; classic is gone from current versions.
{ "compilerOptions": { "module": "nodenext", "moduleResolution": "nodenext" } }
Try it
Resolution happens at compile time, so these examples show the runtime half: how specifiers resolve in Node, which the compiler imitates.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.
Syntax
{ "compilerOptions": { "moduleResolution": "bundler" } }
| Value | Behavior |
|---|---|
nodenext (also node16) |
Node's real rules: exports/imports in package.json, ESM requires full extensions and no directory imports, CommonJS files may omit them. Requires a matching module value. |
bundler |
Like Node's lookup for packages (exports is honored) but relative imports may omit extensions and use directory index files, as bundlers allow. Requires module set to esnext, preserve or similar. |
node10 (node) |
The old CommonJS lookup, with no exports support. Deprecated; keep only for legacy tooling. |
classic |
Obsolete algorithm; removed in current releases. |
Usage notes
- For source files you write
.jsin imports, not.ts:import { x } from "./x.js". The compiler findsx.tsfor you. Newer versions can also rewrite.tsextensions withrewriteRelativeImportExtensions. - Package entry points come from
exportsinpackage.jsonundernodenext/bundler. If a package has no types for the entry, you get "Could not find a declaration file for module". - The
pathsoption remaps specifiers for the type checker only; the runtime or bundler needs the same mapping. import.meta.resolve()(shown above) is a runtime lookup; it does not readtsconfig.json.- Symptoms of a wrong value: imports that work in Vite but fail in Node (
bundlerused for Node code), or "relative import paths need explicit file extensions" errors (nodenextused for bundled code). - Use
tsc --traceResolutionto see every path tried for each specifier.