What is tsconfig.json?

Overview

The tsconfig.json file is an essential configuration file for TypeScript projects. It defines how the TypeScript compiler (tsc) processes .ts files and converts them into .js files. While you can pass compiler options directly via the command line, the tsconfig.json file provides a more organized and efficient way to manage these settings. Additionally, its presence in a directory marks that directory as the root of a TypeScript project.

Introduction to tsconfig.json

At its core, tsconfig.json is a JSON file containing a single object that specifies the configuration for the TypeScript compiler. It defines how TypeScript files are compiled and which files are included or excluded in the compilation process.

Creating tsconfig.json

You can generate a tsconfig.json file by running the following command in the root directory of your project:

tsc --init

This command creates a default tsconfig.json file containing commonly used compiler options, most of which are commented out for clarity.

Common Folder Structure

In most TypeScript projects:

• Source files (.ts) are placed in a src directory where development happens.
• Compiled JavaScript files (.js) are placed in a dist directory.

You can configure this structure using the tsconfig.json file by setting up options like "outDir" for output files and "rootDir" for source files.

Key Properties in tsconfig.json

1. Top-Level Properties

• compilerOptions: Contains various options to control the behavior of the TypeScript compiler.
• files: An array specifying individual files to be included in the compilation.
• include: An array of file patterns to include in the compilation. Supports glob patterns.
• exclude: An array of file patterns to exclude from the compilation. Also supports glob patterns.
• extends: Allows one tsconfig.json to inherit configuration from another.
• references: Defines project references to enable composite projects.

Example:

{
  "compilerOptions": {
    "module": "commonjs",
    "target": "es6",
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules"]
}

Detailed Explanation of Key Properties

compilerOptions

The compilerOptions section controls how TypeScript compiles your code. Below are some common options:

• target: Specifies the ECMAScript version (e.g., ES5, ES6, ESNext) for the compiled code.
• module: Defines the module system for the output (e.g., commonjs, es6, amd).
• strict: Enables all strict type-checking options.
• outDir: Specifies the directory for output files.
• rootDir: Sets the base directory for input files.
• sourceMap: Generates source map files for easier debugging.
• experimentalDecorators: Enables experimental support for decorators

Example:

{
  "compilerOptions": {
    "target": "es6",
    "module": "commonjs",
    "strict": true,
    "outDir": "./dist",
    "rootDir": "./src",
    "sourceMap": true,
    "experimentalDecorators": true
  }
}

files

The files property explicitly specifies the files to include in the compilation. If not set, all .ts files in the project are included (except those excluded using the exclude property).

Example:

{
  "files": ["src/index.ts", "src/app.ts"]
}

include and exclude

• include specifies file patterns to include in the compilation.
• exclude specifies file patterns to exclude from the compilation.

Example:

{
  "include": ["src/**/*.ts"],
  "exclude": ["node_modules", "dist"]
}

extends

The extends property allows the current configuration to inherit from another configuration file, such as a base configuration for specific environments.

Example:

{
  "extends": "@tsconfig/node16/tsconfig.json",
  "compilerOptions": {
    "outDir": "./dist"
  }
}

Advanced Concepts

1. Glob Patterns

Glob patterns are used in include and exclude properties:

• *: Matches zero or more characters.
• ?: Matches a single character.
• **/: Matches any number of subdirectories.

Example:

{
  "include": ["src/**/*"],
  "exclude": ["node_modules"]
}

2. Project References

The references property enables support for composite projects. This is useful for large-scale projects with multiple sub-projects.

{
  "files": [],
  "references": [
    { "path": "./core" },
    { "path": "./utils" }
  ]
}

3. TSConfig Bases

These are community-maintained base configurations for specific environments (e.g., Node.js, React). You can install them via npm.

Example:

{
  "extends": "@tsconfig/react/tsconfig.json"
}

Default Compiler Behavior

When no tsconfig.json is present, the TypeScript compiler uses default settings. However, adding a tsconfig.json provides granular control and flexibility.

Example of Default Behavior:

• Includes all .ts files in the current directory.
• Compiles with default compilerOptions settings like target: "ES3".

Conclusion

The tsconfig.json file is the backbone of any TypeScript project. It allows you to fine-tune how TypeScript compiles your code and manages files. Whether working on a small project or a large enterprise application, understanding tsconfig.json is critical to making the most of TypeScript’s features.

For more detail Follow TS Config