Skip to content
Tutorials Center
My learning

Topics

TypeScript Reference ยท Modules and Declaration Files

Module resolution in TypeScript

How TypeScript turns an import specifier into a file: relative and bare specifiers, extensions, node_modules lookup, package exports and the moduleResolution modes.

Module resolution is the process of turning the text in import x from "specifier" into a file. TypeScript must do this to learn the types of what you import, and it should do it exactly like the program that will run your code, or the checker and the runtime will disagree. The moduleResolution option chooses the algorithm.

A relative specifier (./a.js, ../lib/b.js) is resolved against the importing file's folder. A bare specifier (lodash, @scope/pkg, node:fs) is looked up in node_modules folders from the current directory upward, reading each package's package.json to find the entry point. TypeScript then prefers a type file: for ./a.js it tries a.ts, a.tsx, a.d.ts; for a package it follows exports or types.

JSON
{ "compilerOptions": { "module": "nodenext", "moduleResolution": "nodenext" } }

Try it

TypeScript Extension rules under nodenext (fails on purpose)

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 Watching the runtime resolver

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

The strategy is set in tsconfig.json:

moduleResolution Description
nodenext (also node16) Mirrors Node.js. Relative ES module imports need file extensions, package.json exports and imports are honored, and the format of each file (ES or CommonJS) is decided by its extension and the package type. Use it for code that Node runs.
bundler For code processed by a bundler or a runtime that resolves loosely. Extensionless relative imports and directory index files are allowed, exports is honored, and any module ES-style setting works.
node10 (older name node) The legacy CommonJS algorithm: no exports, directory index files, extensionless paths. Deprecated for new work.
classic A pre-Node algorithm kept for compatibility. Do not use it.

Related options: baseUrl and paths add aliases, rootDirs merge several folders into one virtual root, types and typeRoots choose @types packages, customConditions adds export conditions, and resolvePackageJsonExports and resolvePackageJsonImports switch package maps on or off.

Errors and edge cases:

  • TS2307, Cannot find module or its corresponding type declarations: no file matched.
  • TS2834: Relative import paths need explicit file extensions in ECMAScript imports under nodenext. The first example stops with main.ts(1,24): error TS2834 for exactly that reason. TS2835 is the variant that also suggests the .js spelling when a matching .ts file exists.
  • TS7016: the module resolved to JavaScript with no types, and noImplicitAny is on.

Usage notes

  • Write the extension of the output file. In a .ts source you import ./utils.js; TypeScript finds utils.ts. Importing ./utils.ts needs allowImportingTsExtensions or rewriteRelativeImportExtensions.
  • Pick the algorithm that matches the consumer: nodenext for Node apps and published libraries, bundler for apps built by Vite, webpack, esbuild or similar.
  • module: "nodenext" already implies moduleResolution: "nodenext", and module: "preserve" implies bundler, so you can usually set only module.
  • To see exactly what happened, run tsc --traceResolution or --explainFiles. See traceResolution.
  • The type lookup order for a package: exports conditions (including types), then the types or typings field, then main with a .d.ts next to it, then @types/<name>.
  • Resolution is about files; whether a bare name works at run time depends on your runtime having the same files, which is why path aliases need extra setup there.