The --showConfig Compiler Option in TypeScript

TypeScript 3.2 added a new --showConfig compiler flag to the tsc executable. The command tsc --showConfig calculates the effective tsconfig.json file and prints it to the console. This is useful for debugging configuration issues, particularly when used in conjunction with the extends property in a tsconfig.json file.

#The --showConfig Flag

Let's look at an example to understand what the --showConfig flag does. Going forward, I'm assuming the following directory structure:

.
├── main.ts
├── tsconfig.json
└── utils
    └── crypto.ts

Here's what's inside the tsconfig.json file:

{
  "compilerOptions": {
    "target": "es5",
    "module": "es2015",
    "moduleResolution": "node",
    "strict": true,
    "importHelpers": true
  },
  "include": ["**/*.ts"]
}

Let's now run the following command within the root directory, the one that contains the tsconfig.json file:

tsc --showConfig

The above command will print the following output to the console:

{
  "compilerOptions": {
    "target": "es5",
    "module": "es6",
    "moduleResolution": "node",
    "strict": true,
    "importHelpers": true
  },
  "files": ["./main.ts", "./utils/crypto.ts"],
  "include": ["**/*.ts"]
}

This is the effective configuration that the TypeScript compiler would be using if we were to run the tsc command in this directory.

Notice the files property. It shows all files included in the compilation. We haven't specified that property in our tsconfig.json file; the TypeScript compiler has computed it for us based on our include pattern. In this case, we're only compiling the main.ts and crypto.ts files. In a real-world project, you'd probably see many more files here.

Note that the --showConfig flag does not have any effect when specified within a tsconfig.json file. It can only be used via the command line interface (CLI) of the tsc executable.

#Configuration Inheritance and --showConfig

The tsc --showConfig command is particularly useful for debugging issues with tsconfig.json files that inherit the properties configured in another tsconfig.json file. For this example, I'm assuming the following directory structure:

.
├── client
│   ├── client.ts
│   └── tsconfig.json
├── server
│   ├── server.ts
│   └── tsconfig.json
└── tsconfig.json

Here's what the tsconfig.json file in the root directory looks like. It specifies the properties that we want all nested tsconfig.json files to inherit:

{
  "compilerOptions": {
    "moduleResolution": "node",
    "strict": true,
    "importHelpers": true
  }
}

And here's the tsconfig.json file in the client directory. Notice that it uses the extends property to inherit the configuration from the tsconfig.json file in the parent directory:

{
  "extends": "../tsconfig.json",
  "compilerOptions": {
    "target": "es5",
    "module": "es2015"
  },
  "include": ["**/*.ts"]
}

And here's the tsconfig.json file in the server directory. It, too, extends from the tsconfig.json file in the root directory:

{
  "extends": "../tsconfig.json",
  "compilerOptions": {
    "target": "es2019",
    "module": "commonjs"
  },
  "include": ["**/*.ts"]
}

We can now run the following command to print the effective TypeScript configuration for the tsconfig.json file within our client directory:

tsc --project ./client/tsconfig.json --showConfig

Alternatively, we can shorten the above command by using the -p alias instead of --project. We can also simplify the argument that we're passing to the -p flag; instead of specifying the full path to the tsconfig.json file, we can specify only the folder name:

tsc -p client --showConfig

Both commands are equivalent and print the following output to the console:

{
  "compilerOptions": {
    "moduleResolution": "node",
    "strict": true,
    "importHelpers": true,
    "target": "es5",
    "module": "es6"
  },
  "files": ["./client.ts"],
  "include": ["**/*.ts"]
}

Notice how the properties in the compilerOptions object have been merged together from the two tsconfig.json files:

• The moduleResolution, strict, and importHelpers properties originate from the tsconfig.json file in the root directory. That's why they're listed first.
• The target and module properties originate from the tsconfig.json file in the client directory. They can override any values inherited from the parent configuration (but they don't, in this case).

In the same way, we can print the effective TypeScript configuration for the tsconfig.json file in the server directory:

tsc -p server --showConfig

This command prints the following output to the console:

{
  "compilerOptions": {
    "moduleResolution": "node",
    "strict": true,
    "importHelpers": true,
    "target": "es2019",
    "module": "commonjs"
  },
  "files": ["./server.ts"],
  "include": ["**/*.ts"]
}

And this is it! Hopefully, the --showConfig flag will be helpful to you when debugging your TypeScript configuration files.