tsConfig.json configuration details

The tsconfig.json file is essential for configuring TypeScript projects, providing a wide range of options to control the compilation process. Below is a comprehensive list of tsconfig.json properties along with detailed descriptions and examples for each.

Overall Structure

A typical tsconfig.json file looks like this:

{
  "compilerOptions": {
    // Compiler options go here
  },
  "include": [
    // File patterns to include
  ],
  "exclude": [
    // File patterns to exclude
  ],
  "files": [
    // Specific files to include
  ],
  "references": [
    // References to other tsconfig files for project references
  ],
  "extends": "path/to/base/tsconfig",
  "typeAcquisition": {
    // Type acquisition options for type definitions
  },
  "compileOnSave": true,
  "tsBuildInfoFile": "path/to/tsbuildinfo",
  "watchOptions": {
    // Options for the watch mode
  },
  "assumeChangesOnlyAffectDirectDependencies": true,
  "plugins": [
    // Plugins to extend TypeScript functionality
  ]
}

Detailed Descriptions

compilerOptions

• Purpose: Contains settings that influence the behavior of the TypeScript compiler.
• Type: object

• Common Properties:

  • target: Specifies the output JavaScript version. Common values are "ES5", "ES6", "ES2015", "ES2020", etc. {target": "ES6"}

  • module: Determines the module code generation. Options include "commonjs", "amd", "esnext", etc. {"module": "commonjs"}

  • strict: Enables all strict type-checking options. {"strict": true}

  • outDir: Specifies the output directory for compiled files. { "outDir": "./dist"}

  • rootDir: Specifies the root directory of input files. {"rootDir": "./src"}

  • sourceMap: Generates corresponding .map files for debugging. { "sourceMap": true}

  • declaration: Generates corresponding .d.ts files for TypeScript definitions. {"declaration": true}

  • moduleResolution: Specifies the module resolution strategy, such as "node" or "classic". {"moduleResolution": "node"}

  • lib: Includes standard library files in the compilation. {"lib": ["ES6", "DOM"]}

  • esModuleInterop: Enables interoperability between CommonJS and ES modules. {"esModuleInterop": true}

  • jsx: Specifies the JSX code generation for React. Options are "preserve", "react", "react-jsx", etc. {"jsx": "react"}

  • allowJs: Allows JavaScript files to be compiled. {"allowJs": true}

  • checkJs: Type-checks JavaScript files. {"checkJs": true}

  • baseUrl: Base directory for resolving non-relative module names. {"baseUrl": "./"}

  • paths: A set of path mappings for module resolution. {"paths": { "@app/*": ["src/app/*"] }}

  • typeRoots: Specifies directories containing type definitions. {"typeRoots": ["./node_modules/@types"]}

  • noEmit: Disables the emitting of output files. {"noEmit": true}

  • skipLibCheck: Skips type checking of declaration files. {"skipLibCheck": true}

  • noImplicitAny: Raises errors on expressions and declarations with an implied any type. {"noImplicitAny": true}

  • resolveJsonModule: Enables importing JSON modules. {"resolveJsonModule": true}

  • emitDecoratorMetadata: Emits design-type metadata for decorators. {"emitDecoratorMetadata": true}

  • experimentalDecorators: Enables experimental support for decorators. {"experimentalDecorators": true}

  • incremental: Enables incremental compilation, which speeds up builds. { "incremental": true}

  • composite: Enables project compilation. {"composite": true}

  • tsBuildInfoFile: Specifies the location of the build information file. {"tsBuildInfoFile": "./build/cache/tsbuildinfo.json"}

include

• Purpose: Specifies an array of file patterns to include in the compilation.
• Type: array
• Example: {"include": ["src/**/*", "tests/**/*"]}

exclude

• Purpose: Specifies an array of file patterns to exclude from the compilation.
• Type: array
• Example: {"exclude": ["node_modules", "dist", "build"]}

files

• Purpose: Lists specific files to include in the compilation, regardless of the include and exclude settings.
• Type: array
• Example: {"files": ["src/index.ts", "src/globals.d.ts"]}

references

• Purpose: Specifies a list of project references, allowing TypeScript projects to depend on other TypeScript projects.
• Type: array
• Example: { "references": [ { "path": "../common" }, { "path": "../utilities" } ]}

extends

• Purpose: Allows the tsconfig.json to extend another configuration file.
• Type: string
• Example: { "extends": "./base/tsconfig.json" }

typeAcquisition

• Purpose: Controls the acquisition of type definitions for JavaScript projects.
• Type: object
• Properties:
  • enable: Enables type acquisition. { "enable": true }
  • include: Specifies a list of type definitions to include. { "include": ["jest", "lodash"] }
  • exclude: Specifies a list of type definitions to exclude. { "exclude": ["express"] }

compileOnSave

• Purpose: If set to true, TypeScript will compile files upon saving in the IDE.
• Type: boolean
• Example: { "compileOnSave": true }

tsBuildInfoFile

• Purpose: Specifies the location of the build information file to store incremental compilation information.
• Type: string
• Example: { "tsBuildInfoFile": "./build/cache/tsbuildinfo.json" }

watchOptions

• Purpose: Specifies options for watching files in watch mode.
• Type: object
• Properties:
  • watchFile: Strategy for watching files. { "watchFile": "useFsEvents" }
  • watchDirectory: Strategy for watching directories. { "watchDirectory": "useFsEvents" }
  • fallbackPolling: Polling strategy for systems where fs.watch cannot be used. { "fallbackPolling": "dynamicPriority" }

assumeChangesOnlyAffectDirectDependencies

• Purpose: When set to true, TypeScript assumes changes only affect direct dependencies, which can speed up incremental builds.
• Type: boolean
• Example: { "assumeChangesOnlyAffectDirectDependencies": true }

plugins

• Purpose: Specifies a list of plugins that extend TypeScript's functionality.
• Type: array
• Example: { "plugins": [ { "name": "typescript-tslint-plugin" }, { "name": "typescript-styled-plugin" } ] }