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
baseUrlorpathsconfiguration working? - Package resolution issues: Which
package.jsonfields 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.