Home » Programming » Javascript » TypeScript » Tsconfig
📌 Pin 🔗 Copy Link 📋 Copy Markdown ⬇️ Download
3 min read

In-Depth Guide to tsconfig.json

The tsconfig.json file is the heart of a TypeScript project. It specifies the root files and the compiler options required to compile the project. Its presence in a directory indicates that the directory is the root of a TypeScript project.

1. Initialization

You can generate a tsconfig.json file with default settings and extensive comments by running:

tsc --init

2. Top-Level Properties

The file has several key top-level properties:

  • compilerOptions: The most important section, containing all the settings for the TypeScript compiler.
  • include: An array of glob patterns specifying which files to include in the compilation. If not specified, it defaults to all TypeScript files (**/*) in the project directory.
  • exclude: An array of glob patterns specifying which files to exclude from compilation. node_modules is excluded by default.
  • files: An array of file paths to explicitly include. This is less common than include.
  • extends: A path to another configuration file to inherit from.

3. Key compilerOptions

This section controls how TypeScript checks and emits your code.

A. Type Checking

These options are crucial for leveraging TypeScript's safety features.

  • "strict": true: Enables all strict type-checking options. It's highly recommended to keep this on. It includes:
    • "noImplicitAny": true: Raise error on expressions and declarations with an implied any type.
    • "strictNullChecks": true: When true, null and undefined have their own distinct types and you'll get a type error if you try to use them where a concrete value is expected.
    • "strictFunctionTypes": true: Enable strict checking of function types.
    • "strictPropertyInitialization": true: Ensure non-undefined class properties are initialized in the constructor.

These define how modules are resolved and generated.

  • "module": "commonjs": Specifies the module system for the generated code.
    • commonjs: For Node.js.
    • es2015, es2020, esnext: For modern browsers that support ES modules.
  • "moduleResolution": "node": How the compiler looks for a module. node is the standard for most projects.
  • "rootDir": "./src": Specifies the root directory of input files. Only files under this directory are compiled.
  • "baseUrl": "./": Base directory to resolve non-absolute module names. Often used with paths.
  • "paths": { "@/*": ["src/*"] }: Creates aliases for module paths. In this example, import MyComponent from '@/components/MyComponent' would resolve to src/components/MyComponent.ts.

C. Emit Options

These control the output of the compilation process.

  • "target": "es2016": The JavaScript language version for the emitted code. es2016 is a safe default. Use esnext for the latest features if your runtime supports them.
  • "outDir": "./dist": Redirect output structure to the specified directory. All compiled .js files will go here.
  • "sourceMap": true: Generates corresponding .map files, which allow debuggers to map the compiled JavaScript back to the original TypeScript source.
  • "declaration": true: Generates corresponding .d.ts files, which are type definition files. Essential if you are building a library.
  • "removeComments": true: Do not emit comments to output.

D. JavaScript Support

  • "allowJs": true: Allow JavaScript files to be compiled.
  • "checkJs": true: Report errors in .js files. Requires allowJs.

E. Interoperability

  • "esModuleInterop": true: Enables compatibility with different module systems (CommonJS vs. ES Modules). It fixes issues where you might have to do import * as React from 'react' instead of import React from 'react'. Almost always recommended to be true.

4. Extending Configuration

The extends property allows you to create a base configuration and then specialize it for different environments (e.g., one for production builds, one for tests).

tsconfig.base.json

{
  "compilerOptions": {
    "target": "es2020",
    "module": "commonjs",
    "strict": true,
    "esModuleInterop": true
  }
}

tsconfig.json

{
  "extends": "./tsconfig.base.json",
  "include": ["src/**/*"],
  "exclude": ["node_modules", "tests"]
}

Example: tsconfig.json for a Node.js Project

{
  "compilerOptions": {
    /* Type Checking */
    "strict": true,

    /* Modules */
    "module": "commonjs",
    "rootDir": "./src",
    "moduleResolution": "node",
    "baseUrl": "./",
    "paths": {
      "@/*": ["src/*"]
    },

    /* Emit */
    "outDir": "./dist",
    "target": "es2020",
    "sourceMap": true,
    "removeComments": true,

    /* Interop */
    "esModuleInterop": true,
    "forceConsistentCasingInFileNames": true,

    /* Completeness */
    "skipLibCheck": true
  },
  "include": ["src/**/*.ts"],
  "exclude": ["node_modules"]
}

programming/javascript/typescript/typescript

Created: March 17, 2026 • Last Modified: January 30, 2026