TypeScript — tsconfig.json Explained: Configuration, Fields, and Best Practices

Introduction – What is tsconfig.json in TypeScript?

In a TypeScript project, the tsconfig.json file is the central configuration hub. It tells the TypeScript compiler (tsc) how to compile your project, which files to include, and what compilation settings to use. Without tsconfig.json, you’d have to pass flags and options to the compiler every time — making it inefficient and error-prone.

Whether you’re building a small utility or a large-scale application, mastering tsconfig.json ensures that your project is type-safe, optimized, and scalable.

In this guide, you’ll learn:

• What tsconfig.json does
• Common compiler options explained
• File inclusion and exclusion patterns
• Best practices and real-world examples

What is tsconfig.json?

The tsconfig.json file is a JSON file that specifies the root files and compiler options required to compile a TypeScript project.

When TypeScript sees a tsconfig.json in your project directory, it uses that file to automatically understand how to build the project without additional CLI flags.

Create tsconfig.json using:

npx tsc --init

This generates a default tsconfig.json with all common options commented for customization.

Basic Structure of tsconfig.json

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

Main Sections:

• compilerOptions: How TypeScript compiles code
• include: Files/folders to include
• exclude: Files/folders to ignore
• files: Specific files to compile (if include is omitted)

Essential compilerOptions Explained

Here’s a breakdown of the most useful compilerOptions settings:

1️⃣ target

Specifies the JavaScript version output.

"target": "ES6"

Options: ES3, ES5, ES6 (ES2015), ES2020, ESNext, etc.
Use the latest version supported by your runtime environment.

2️⃣ module

Specifies the module system for bundlers or Node.js.

"module": "commonjs"

Options: commonjs, esnext, amd, system, umd, node16

3️⃣ strict

Enables all strict type-checking options.

"strict": true

Includes:

• noImplicitAny
• strictNullChecks
• strictFunctionTypes
• strictBindCallApply
• alwaysStrict

Highly recommended for catching bugs early.

4️⃣ outDir

Specifies the output folder for compiled JavaScript files.

"outDir": "./dist"

5️⃣ rootDir

Sets the root folder of your source TypeScript files.

"rootDir": "./src"

6️⃣ esModuleInterop

Allows interoperability between CommonJS and ES modules.

"esModuleInterop": true

Required for import express from 'express' syntax.

7️⃣ forceConsistentCasingInFileNames

Ensures file imports use consistent casing (helpful in cross-platform development).

"forceConsistentCasingInFileNames": true

8️⃣ skipLibCheck

Skips type checking of declaration files to speed up build.

"skipLibCheck": true

Useful for projects with many third-party types.

include / exclude / files

include

Defines files or folders to compile:

"include": ["src"]

exclude

Tells TypeScript which files or folders to ignore:

"exclude": ["node_modules", "dist"]

files

If you want to compile only specific files:

"files": ["src/index.ts", "src/util.ts"]

You typically use include and exclude together for folders, and files for explicit entry points.

Other Useful Compiler Options

Real-World tsconfig.json Example

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "moduleResolution": "node",
    "lib": ["ES2020", "DOM"],
    "declaration": true,
    "strict": true,
    "esModuleInterop": true,
    "outDir": "./build",
    "rootDir": "./src",
    "resolveJsonModule": true,
    "forceConsistentCasingInFileNames": true,
    "skipLibCheck": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "build"]
}

Ideal for modern web applications or libraries using ESM.

Summary – Understanding tsconfig.json in TypeScript

The tsconfig.json file is the heart of your TypeScript setup, giving you complete control over how your code is compiled and validated. By configuring the right options, you can dramatically improve your project’s reliability, maintainability, and development experience.

Key Takeaways:

• tsconfig.json defines how TypeScript compiles your code.
• compilerOptions includes settings like target, module, strict, and outDir.
• include, exclude, and files determine which files are compiled.
• Enabling strict settings helps catch errors early.
• Customize tsconfig.json to match your environment (Node.js, browser, etc.)

Real-World Relevance:

• Consistent build behavior across teams
• Faster debugging with source maps
• Better code quality with stricter type checks
• Smooth integration with modern build tools (Webpack, Vite, etc.)

FAQs – TypeScript tsconfig.json

What is the purpose of tsconfig.json?

It tells the TypeScript compiler how to compile your project — including which files to include, what ECMAScript version to use, and what rules to apply.

How do I generate a tsconfig.json file?

Run the following command in your terminal:

npx tsc --init

This creates a default tsconfig.json file with commonly used settings.

What’s the difference between include, exclude, and files?

• include: Folders or files to compile
• exclude: Folders or files to ignore
• files: Specific files to compile (overrides include)

Is tsconfig.json required for all TypeScript projects?

No, but it’s highly recommended. Without it, you’d need to pass compiler options manually, which is impractical for larger projects.

What happens if I set strict: true?

It enables all strict type-checking features, including:

• No implicit any
• Null/undefined checks
• Function parameter enforcement

Can I have multiple tsconfig.json files?

Yes. You can use project references or extend another config:

{
  "extends": "./tsconfig.base.json"
}