Compiler Diagnostics

diagnostics Deprecated

• Released: 1.0

• Related: extendedDiagnostics

Used to output diagnostic information for debugging. This command is a subset of extendedDiagnostics which are more user-facing results, and easier to interpret.

If you have been asked by a TypeScript compiler engineer to give the results using this flag in a compile, in which there is no harm in using extendedDiagnostics instead.

explainFiles

• Released: 4.2

Print names of files which TypeScript sees as a part of your project and the reason they are part of the compilation.

For example, with this project of just a single index.ts file

example
├── index.ts
├── package.json
└── tsconfig.json

Using a tsconfig.json which has explainFiles set to true:

{
  "compilerOptions": {
    "target": "es5",
    "module": "commonjs",
    "explainFiles": true
  }
}

Running TypeScript against this folder would have output like this:

❯ tsc
node_modules/typescript/lib/lib.d.ts
  Default library for target 'es5'
node_modules/typescript/lib/lib.es5.d.ts
  Library referenced via 'es5' from file 'node_modules/typescript/lib/lib.d.ts'
node_modules/typescript/lib/lib.dom.d.ts
  Library referenced via 'dom' from file 'node_modules/typescript/lib/lib.d.ts'
node_modules/typescript/lib/lib.webworker.importscripts.d.ts
  Library referenced via 'webworker.importscripts' from 
    file 'node_modules/typescript/lib/lib.d.ts'
node_modules/typescript/lib/lib.scripthost.d.ts
  Library referenced via 'scripthost' 
    from file 'node_modules/typescript/lib/lib.d.ts'
index.ts
  Matched by include pattern '**/*' in 'tsconfig.json'

The output above show:

• The initial lib.d.ts lookup based on target, and the chain of .d.ts files which are referenced
• The index.ts file located via the default pattern of include

This option is intended for debugging how a file has become a part of your compile.

extendedDiagnostics

• Released: 2.0

• Related: diagnostics

You can use this flag to discover where TypeScript is spending its time when compiling. This is a tool used for understanding the performance characteristics of your codebase overall.

You can learn more about how to measure and understand the output in the performance section of the wiki.

generateCpuProfile

• Default: profile.cpuprofile

• Released: 3.7

This option gives you the chance to have TypeScript emit a v8 CPU profile during the compiler run. The CPU profile can provide insight into why your builds may be slow.

This option can only be used from the CLI via: --generateCpuProfile tsc-output.cpuprofile.

npm run tsc --generateCpuProfile tsc-output.cpuprofile

This file can be opened in a chromium based browser like Chrome or Edge Developer in the CPU profiler section. You can learn more about understanding the compilers performance in the TypeScript wiki section on performance.

generateTrace

• Released: 4.1

Generates an event trace and a list of types.

listEmittedFiles

• Released: 2.0

Print names of generated files part of the compilation to the terminal.

This flag is useful in two cases:

• You want to transpile TypeScript as a part of a build chain in the terminal where the filenames are processed in the next command.
• You are not sure that TypeScript has included a file you expected, as a part of debugging the file inclusion settings.

For example:

example
├── index.ts
├── package.json
└── tsconfig.json

With:

{
  "compilerOptions": {
    "declaration": true,
    "listEmittedFiles": true
  }
}

Would echo paths like:

$ npm run tsc

path/to/example/index.js
path/to/example/index.d.ts

Normally, TypeScript would return silently on success.

listFiles

• Released: 1.5

• Related: explainFiles

Print names of files part of the compilation. This is useful when you are not sure that TypeScript has included a file you expected.

For example:

example
├── index.ts
├── package.json
└── tsconfig.json

With:

{
  "compilerOptions": {
    "listFiles": true
  }
}

Would echo paths like:

$ npm run tsc
path/to/example/node_modules/typescript/lib/lib.d.ts
path/to/example/node_modules/typescript/lib/lib.es5.d.ts
path/to/example/node_modules/typescript/lib/lib.dom.d.ts
path/to/example/node_modules/typescript/lib/lib.webworker.importscripts.d.ts
path/to/example/node_modules/typescript/lib/lib.scripthost.d.ts
path/to/example/index.ts

Note if using TypeScript 4.2, prefer explainFiles which offers an explanation of why a file was added too.

noCheck

• Released: 5.6

Disable full type checking (only critical parse and emit errors will be reported).

traceResolution

• Released: 2.0

When you are trying to debug why a module isn't being included. You can set traceResolution to true to have TypeScript print information about its resolution process for each processed file.