The tsconfig.json file allows you to specify the root level files and the compiler options that requires to compile a TypeScript project. The presence of this file in a directory specifies that the said directory is the TypeScript project root.

In this chapter of the TypeScript Tutorial series, we will learn about tsconfig.json, its various properties and how to extend it.

In the previous chapters of this TypeScript Tutorial series, we learned how to install Node.js and TypeScript, followed by building your first HelloWorld application in TypeScript using Visual Studio Code. Today in this article, let's go one step ahead to learn about tsconfig.json file.

The "compilerOptions" Property

The "compilerOptions" property allows you to specify additional options to the TypeScript compiler. Here's a list of few optional settings part of the compilerOptions property that you may need most of the time: listFiles, module, outDir, outFile, rootDir, sourceRoot, allowUnreachableCode, allowJs, noImplicitUseStrict, strictNullChecks and more.

Here's a sample JSON file describing how you can define a tsconfig.json file containing different parameters of the compilerOptions property:

{
    "compilerOptions": {
        "module": "system",
        "noImplicitAny": true,
        "removeComments": true,
        "allowUnreachableCode": false,
        "strictNullChecks": true,
        "outFile": "../JS/TypeScript/HelloWorld.js",
        "sourceMap": true
    }
}

The "compileOnSave" Property

The "compileOnSave" property can be used to direct the IDE to automatically compile the included TypeScript files and generate the output. Here's how you can define the compileOnSave property inside a tsconfig.json file, along with the other properties:

{
   "compileOnSave": true,
   "compilerOptions": {
        "module": "system",
        "noImplicitAny": true,
        "removeComments": true,
        "allowUnreachableCode": false,
        "strictNullChecks": true,
        "outFile": "../JS/TypeScript/HelloWorld.js",
        "sourceMap": true
   }
}

The "files", "include" and "exclude" Properties

• The "files" property allows you to specify a list of TypeScript files that will be included by the compiler. The URL of the files can be relative or absolute.
• The "include" property allows you to include a list of TypeScript files using the glob wildcards pattern.
• The "exclude" property allows you to exclude a list of TypeScript files using the glob wildcards pattern.
• When you don't specify both the files and include properties, the compiler includes all TypeScript files (*.ts, *.d.ts, *.tsx) by default.
• When both the files and include properties are specified, the compiler includes the union of the specified files.
• When you want to filter out some files included using the include property, you can specify exclude property.
• If you specify any files using the files property, the uses of exclude property will not have any impact to those listed files. In short, the files included using the files property will always include regardless the files listed under the exclude property.

Here's the code snippet describing how you can define the files, include and exclude properties inside a tsconfig.json file, along with the other properties:

{
   "compileOnSave": true,
   "compilerOptions": {
        "module": "system",
        "noImplicitAny": true,
        "removeComments": true,
        "allowUnreachableCode": false,
        "strictNullChecks": true,
        "outFile": "../JS/TypeScript/HelloWorld.js",
        "sourceMap": true
   },
    "files": [
        "program.ts",
        "sys.ts"
    ],
    "include": [
        "src/**/*"
    ],
    "exclude": [
        "node_modules",
        "src/**/*.spec.ts"
    ]
}

Extending the "tsconfig.json" File

You can also extend a TypeScript configuration file from a different base configuration. You can do so by using the extends property. It accepts a string value containing a path to another configuration file to inherit from. The configuration from the base file are loaded first, then overridden by those in the inheriting config file. In case there is a circular reference, TypeScript compiler will return an error.

// tsconfig-base.json
{
    "compilerOptions": {
        "module": "system",
        "noImplicitAny": true,
        "removeComments": true,
        "allowUnreachableCode": false,
        "strictNullChecks": true
    }
}

// tsconfig.json
{
    "extends": "./tsconfig-base",
    "compilerOptions": {
        "outFile": "../JS/TypeScript/HelloWorld.js",
        "sourceMap": true
    }
}

👉 TypeScript Tutorial - Getting started with TypeScript