Learning about tsconfig.json file in TypeScript Projects

by

Introduction

  • The Heart of Your TypeScript Project: A tsconfig.json file acts as the central configuration hub for your TypeScript project. It tells the TypeScript compiler (TSC) how to transform your TypeScript code into usable JavaScript.
  • Root Signal: The presence of a tsconfig.json file signifies that the directory it lives in is the root of your TypeScript project.

Why use a tsconfig.json file?

  1. Customization: It allows you to tailor the TypeScript compiler’s behavior to match your project’s specific needs and preferences.
  2. Consistency: It ensures that all developers working on the project use the same compiler settings, leading to a more consistent codebase.
  3. Efficiency: You can avoid long and repetitive command-line flags when using the tsc (TypeScript compiler) command. The tsconfig.json stores your settings.

Key Sections within tsconfig.json

Let’s focus on the most important section for understanding how to configure your project:

  • compilerOptions: This is where you’ll find the bulk of the settings that control the TypeScript compiler’s behavior. Some of the most important include:
    • target: Specifies the JavaScript language version you want your TypeScript code compiled into (e.g., “ES5”, “ES2020”).
    • module: Determines the module system your compiled code will use (e.g., “CommonJS”, “AMD”, “ES2015”).
    • outDir: Specifies the directory where compiled JavaScript files will be placed.
    • rootDir: Specifies the root directory for input source files.
    • strict: Enables stricter type checking for a more robust codebase.
    • sourceMap: Generates .map files to help with debugging the compiled JavaScript code.
  • include: An array of file paths or glob patterns to specify the TypeScript files to include in the compilation process.
  • exclude: An array of file paths or glob patterns to specify files that should be excluded from the compilation process.

Sameple tsconfig.json file

{
    "compilerOptions": {
        "target": "es2020",
        "lib": [
            "es2020"
        ],
        "module": "commonjs",
        "strict": true,
        "strictPropertyInitialization": false,
        "esModuleInterop": true,
        "skipLibCheck": true,
        "forceConsistentCasingInFileNames": true,
        "sourceMap": true,
        "outDir": "./dist",
        "incremental": true,
        "noErrorTruncation": true,
        "listEmittedFiles": true,
    },
    "type": "module",
    "include": [
        "src/**/*.ts",
        "*.ts",
        "src/**/*.tsx",
        "*.tsx"
    ]
}

Some Options

strictPropertyInitialization

strictPropertyInitialization is a strict type checking option in TypeScript. When set to true in your tsconfig.json file, TypeScript will ensure that each instance property of a class gets initialized in the constructor body, or by a property initializer.

For example, consider the following TypeScript class:

class MyClass {
  myProp: number;
}

If strictPropertyInitialization is set to true, TypeScript will throw an error because myProp is not initialized. To fix the error, you need to initialize myProp in the constructor or directly at declaration:

class MyClass {
  myProp: number = 0; // Initialized at declaration

  constructor() {
    this.myProp = 0; // Or initialized in the constructor
  }
}

lib

The lib option in the TypeScript configuration file (tsconfig.json) is used to specify a list of library files to be included in the compilation.

"lib": ["es2020"] means that TypeScript code will be compiled with the library files that correspond to the ES2020 version of JavaScript. This includes all the built-in JavaScript objects and functions that are part of the ES2020 specification, such as BigInt, Promise.allSettled, global this, etc.

This option allows you to write TypeScript code that uses these ES2020 features, and it will be correctly type-checked and compiled to your target JavaScript version (specified by the target option in tsconfig.json). If you use a feature that is not included in the specified library, TypeScript will give a compile error.

esModuleInterop

The esModuleInterop option in the TypeScript configuration file (tsconfig.json) is used to enable a more compatible CommonJS/AMD module emit.

In JavaScript, there’s a difference between import foo from 'foo' and import * as foo from 'foo'. The former is known as a default import and the latter is known as a namespace import.

However, when importing CommonJS modules (which is the type of module used in Node.js), this distinction does not exist. In CommonJS, you can use const foo = require('foo') for both cases.

When esModuleInterop is set to true, TypeScript will allow you to use default imports syntax for CommonJS modules for a smoother interoperability between modules.

skipLibCheck

The skipLibCheck option in the TypeScript configuration file (tsconfig.json) is used to skip type checking of declaration files (*.d.ts).

When this option is set to true, TypeScript will skip checking the correctness of the types declared in these files. This can significantly speed up the TypeScript compilation process, especially in larger projects with many dependencies.

forceConsistentCasingInFileNames

The forceConsistentCasingInFileNames option in the TypeScript configuration file (tsconfig.json) ensures that the casing of your import statements matches the casing of the files in your file system.

import { MyComponent } from './myComponent';

If the actual file name is MyComponent.ts (note the uppercase ‘M’), and forceConsistentCasingInFileNames is set to true, TypeScript will throw an error because the casing in the import statement does not match the casing of the actual file name.

incremental

The incremental option in the TypeScript configuration file (tsconfig.json) is used to enable incremental compilation.

When this option is set to true, TypeScript will save information about the previous compilation to a .tsbuildinfo file. This file is then used in subsequent compilations to speed up the TypeScript build process by only checking and emitting files that have changed (or may have been affected by changes) since the last compilation.

noErrorTruncation

The noErrorTruncation option in the TypeScript configuration file (tsconfig.json) is used to control the truncation of error messages.

By default, TypeScript might truncate certain error messages if they are too long. This is done to prevent the output from being overwhelmed with information that might not be useful.

When noErrorTruncation is set to true, TypeScript will not truncate error messages, and will instead output the full details of every error. This can be useful if you’re debugging a complex issue and need to see the entire error message.

For all the options, check this : TypeScript: TSConfig Reference – Docs on every TSConfig option (typescriptlang.org)

Leave a comment