Skip to content
Tutorials Center
My learning

Topics

TypeScript Reference ยท tsconfig: Projects, Files and Watch Options

TypeScript traceResolution option

Reference for the TypeScript traceResolution option: log every step of module resolution to find why an import is not found or resolves to the wrong file.

When an import fails with "Cannot find module" or resolves to an unexpected file, traceResolution shows why. With the option on, the compiler prints each module lookup: the import specifier, the importing file, the resolution mode in use, every candidate path it tried, and the file it finally chose (or the failure).

It is a diagnostic option; it does not alter the program. Pair it with moduleResolution and module when you debug.

TEXT
tsc --noEmit --traceResolution

Try it

The real log depends on your folders. These examples reproduce the candidate order for a relative import in a classic Node-style lookup, which is what you will see in the log.

TypeScript Candidate paths for a relative import

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 Finding the first match

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": { "traceResolution": true } }
TEXT
tsc --traceResolution

A typical log line begins with ======== Resolving module './util' from '/project/src/main.ts'. ======== and ends with ======== Module name './util' was successfully resolved to '/project/src/util/index.ts'. ========. Between them are lines such as "File '/project/src/util.ts' does not exist." and the strategy in use.

Usage notes

  • Search the log, not read it. Pipe it to a file and search for the specifier you care about.
  • Check the strategy line. The resolution mode printed at the top tells you whether node10, node16/nodenext or bundler rules applied.
  • Extensions. In nodenext, relative imports in ES modules need real extensions (./util.js), and the log shows candidates with that extension.
  • paths and baseUrl lookups appear as separate attempts before regular node_modules walking.
  • Types for packages. The log also shows package.json exports, types and typesVersions fields being consulted.
  • Large output. Use it on a single file with --noEmit rather than a whole monorepo.