Course contentsShow
← TypeScript
Lesson 1120 of 1,79626. Modules in TypeScriptFree lesson

Module Resolution Tracing with --traceResolution

Using the compiler flag to debug exactly how TypeScript resolves each import.

Module Resolution Tracing with --traceResolution

What you'll learn: How to use the --traceResolution compiler flag to see exactly how TypeScript finds (or fails to find) each imported module.

The Problem: Module Resolution Is Hidden

When TypeScript compiles your code, it has to find every imported module by following complex resolution rules—checking node_modules, respecting package.json fields, applying paths mappings, and more. When an import fails or resolves to the wrong file, the error messages don't always explain why.

What --traceResolution Does

The --traceResolution flag makes TypeScript log every step of its module resolution process to the console. It's like turning on X-ray vision for imports—you see exactly which directories TypeScript checks, which files it considers, and why it chooses (or rejects) each candidate.

Basic Usage

Add the flag when running tsc:

tsc --traceResolution

Or add it to your tsconfig.json:

{
  "compilerOptions": {
    "traceResolution": true
  }
}

Reading the Output

TypeScript will log entries like:

======== Resolving module './user' from '/src/app.ts'. ========
Module resolution kind is not specified, using 'NodeJs'.
Loading module as file / folder, candidate module location '/src/user', target file types: TypeScript, Declaration.
File '/src/user.ts' exists - use it as a name resolution result.
======== Module name './user' was successfully resolved to '/src/user.ts'. ========

You'll see failed attempts too—TypeScript showing it looked for a file that doesn't exist, tried different extensions, or skipped paths that didn't match.

When to Use It

  • Debugging import errors: Why can't TypeScript find your module?
  • Understanding paths mappings: Is your baseUrl or paths configuration working?
  • Package resolution issues: Which package.json fields is TypeScript respecting?
  • Optimizing configuration: See if TypeScript is checking unnecessary paths

The Trade-off

The output is extremely verbose. You'll get dozens of lines per import. Use it targeted: enable it temporarily when debugging a specific issue, then turn it off.

Key Takeaway: --traceResolution is your debugging tool for module resolution—it reveals TypeScript's entire search process, making hidden import problems visible and solvable.