What is tsconfig.json?

Introduction to tsconfig.json

Using tsconfig.json or jsconfig.json

• Invoking tsc --init in the command line creates a tsconfig.json file in the current directory.
  • Creating the config file using the above approach creates a file with all the top-level options but most of the available options are commented out, except for the common ones for e.g "compilerOptions" which has several properties that define how the compilation process is done.

Example of tsconfig.json files:

There are various options on the root level of tsconfig.json (top-level options):

• compilerOptions contains a bunch of options that can be used to configure the TypeScript compiler

• "files" is an array of filenames that are allowed to be included in the program. This does not allow the use of glob operators.

• "extends" is a string that has a path to another configuration file. The present configuration file inherits/extends from the configuration file at the mentioned path.

• "include" is an array of filenames that are to be included in the program. This supports glob operators as opposed to the "files" option.

• "exclude" is an array of filenames that should be skipped when including files mentioned in the "include" option.

• "references" is an array of objects that specifies projects to reference.

Examples

tsc compiler uses its default compiler configurations when compilerOptions property is omitted.

Like compilerOptions, the tsc compiler has other root-level properties like files, include, exclude, etc. Below are examples of tsconfig json file using root-level properties mentioned above:

1. Using files Property

• files property takes in a list of absolute or relative file path.
• files property specifies the list of files to include in the program. All mentioned files must be present in the project or it will cause an error.
• files when left unspecified, the tsc compiler includes all TypeScript files except the files that have been excluded by the exclude property.
• files that are included explicitly using the files property are always included regardless of the exclude property.
• if files and include both properties are specified, files that are included in either of them or both of them are included.

2. Using the include and exclude Properties

• include and exclude properties take a list of glob-like file patterns. There are 3 supported glob wildcards:
  • * - used to match zero or more characters
  • ?- used to match a single character
  • **/ - used to match any subdirectory recursively

TSConfig Bases

TSConfig Bases are tsconfig.json files that are made for a particular runtime environment that can be used to allow support for any runtime in an existing TypeScript project.

TSConfig Bases are owned and updated by the TypeScript community and are hosted on GitHub.

Let's take an example: If we're building a website using create-react-app, then, we can use the npm module @tsconfig/create-react-app:

compilerOptions

• compilerOptions is a root level property of tsconfig.json which modifies the compilation parameters of the tsccompiler.
  • When compilerOptions is omitted, tsc compiles based on default configurations.

Below is the list of all the options/parameters in the compilerOptions root property and their intended use:

@types, typeRoots and types

• By default all visible @types packages are included in the compilation when the tsc compiler is invoked
• files or packages in node_modules/@types are considered visible
• If typeRoots is specified, only packages under typeRoots will be included

• If types is specified, only packages listed in types will be included.

Configuring Inheritance With Extends

• "extends" option is a string containing the path of another configuration file used to configure the tsc compiler
  • The configuration settings are first loaded from the inherited configuration file(the file that we are referencing)
  • then the configuration settings are extended by the current configuration file.
  • There is a union of both configuration files.
• extends allows us to use TSConfig Bases which allows the TypeScript project to support different runtime environments like create-react-app.

compileOnSave

• compileOnSave is a root level option in tsconfig.json
• compileOnSave indicates the compiler to re-compile all included .ts files when saving is detected by the IDE.
• This can be set up in some specific IDEs, like Visual Studio, which can trigger the compileOnSave option when the code is saved.
• compileOnSave is IDE dependent for it to work properly and the compilation is triggered when onSave is triggered.
• watch mode can also be used by the tsc compiler to keep re-compiling updated TypeScript files.
• compileOnSave is only available in Visual Code IDE as of now
  • TypeScript community wants to incorporate compileOnSave into the TypeScript compiler, tsc, itself so that it can be used to configure it with any IDE.

Schema

• A JSON Schema is a JSON file that defines the structure of similar JSON files and is used to validate JSON documents.
• JSON Schema is an IETF (Internet Engineering Task Force) standard providing a format for what JSON data is required for a given application and how to interact with it.