Skip to content
Tutorials Center
My learning

Topics

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.

JSON
{ "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.

TypeScript Specifiers resolve like URLs

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.

TypeScript Built-in modules and import.meta.resolve

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

JSON
{ "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 .js in imports, not .ts: import { x } from "./x.js". The compiler finds x.ts for you. Newer versions can also rewrite .ts extensions with rewriteRelativeImportExtensions.
  • Package entry points come from exports in package.json under nodenext/bundler. If a package has no types for the entry, you get "Could not find a declaration file for module".
  • The paths option 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 read tsconfig.json.
  • Symptoms of a wrong value: imports that work in Vite but fail in Node (bundler used for Node code), or "relative import paths need explicit file extensions" errors (nodenext used for bundled code).
  • Use tsc --traceResolution to see every path tried for each specifier.