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.
{ "compilerOptions": { "module": "nodenext", "moduleResolution": "nodenext" } }
Try it
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
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 withmain.ts(1,24): error TS2834for exactly that reason. TS2835 is the variant that also suggests the.jsspelling when a matching.tsfile exists. - TS7016: the module resolved to JavaScript with no types, and
noImplicitAnyis on.
Usage notes
- Write the extension of the output file. In a
.tssource you import./utils.js; TypeScript findsutils.ts. Importing./utils.tsneedsallowImportingTsExtensionsorrewriteRelativeImportExtensions. - Pick the algorithm that matches the consumer:
nodenextfor Node apps and published libraries,bundlerfor apps built by Vite, webpack, esbuild or similar. module: "nodenext"already impliesmoduleResolution: "nodenext", andmodule: "preserve"impliesbundler, so you can usually set onlymodule.- To see exactly what happened, run
tsc --traceResolutionor--explainFiles. See traceResolution. - The type lookup order for a package:
exportsconditions (includingtypes), then thetypesortypingsfield, thenmainwith a.d.tsnext 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.
Related
- Path mapping, package.json exports, moduleResolution
- Lessons: Modules, tsconfig