TypeScript tsconfig.json Configuration

This chapter explains the tsconfig.json file: what it is for, the settings you will meet most often, and how to avoid common mistakes.

The tsconfig.json file is the heart of every TypeScript project.

It tells the TypeScript compiler how to process your code, which files belong to the project, and which features to turn on or off.

A well set-up tsconfig.json gives you a smooth development experience and reliable builds.

The most important top-level fields are:

• compilerOptions: controls how TypeScript compiles your code (for example the target, the module system, and strictness).
• include: files or folders to include in the compilation.
• exclude: files or folders to leave out.
• files: an explicit list of files to include (rarely used together with include).
• extends: inherit options from another config file.
• references: enable project references for monorepos or multi-package setups.

A minimal tsconfig.json only needs a target, a module system, and the files to include:

• "compilerOptions": { "target": "es6", "module": "commonjs" }
• "include": ["src/**/*"]

A more complete config for an app adds strict checking, path aliases, and an output folder:

• "target": "es2020"
• "module": "esnext"
• "strict": true
• "baseUrl": "."
• "paths": { "@app/*": ["src/app/*"] }
• "outDir": "dist"
• "esModuleInterop": true
• "include": ["src"]
• "exclude": ["node_modules", "dist"]

To generate a starter tsconfig.json with comments for every option, run tsc --init.

• Monorepo: use references and extends to share settings across packages.
• Library: set declaration and outDir so type definition files are produced next to the JavaScript output.
• App: use strict and esModuleInterop for the best compatibility.

• A wrong include or exclude can make files disappear from the build, or pull in files you did not expect.
• Paths not resolving? Check the baseUrl and paths settings.
• New type errors after turning on strict? That is expected. Go through the reported code and make it type-safe.

• Always enable strict for safer code.
• Use extends so you do not repeat the same config in monorepos or across several projects.
• Do not commit build output folders (such as dist) to version control.