Chapter 8.1☕ 17 min read

tsconfig.json Essentials

tsconfig = Nizam ka farmaish, compiler ko kaise chalana hai!

01The Darbar Rulebook

Every TypeScript project needs a tsconfig.json file — it's the Nizam's Darbar Rulebook. This file tells the TypeScript compiler HOW to behave, which files to include, what rules to enforce, and where to put the output. Without it, TypeScript uses default settings which are often too loose and permissive for production code. With it, you control the entire kingdom and enforce the standards your project deserves.

Think of the Nizam's Darbar. It has strict protocols — who sits where, what language is spoken, how petitions are processed, what dress code is required. These rules aren't optional suggestions — they're written in the official royal decree and everyone must follow them. tsconfig.json is that decree for your TypeScript project. It declares: "Include only the src folder (the darbar hall), enforce strict rules (no loose talk in my court), compile to ES2020 (modern communication standards), and output to dist (the public square where results are displayed)."

Without the decree, everyone does whatever they want — chaos in the kingdom! Variable types go unchecked, files from random folders get compiled, and the output structure is a mess. With the decree, the entire kingdom runs smoothly. The compiler knows exactly what to do, where to look, and how strict to be. Seedha samjho: tsconfig = Nizam ka farmaish, compiler ko kaise chalana hai! This single file is the foundation of every well-organized TypeScript project, and understanding it is essential for professional development.

02Core Compiler Options

The most important settings live inside the compilerOptions object of your tsconfig.json. Each option controls a different aspect of how TypeScript compiles and checks your code. Let's walk through the essential ones that every project needs.

A Basic Config:

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames":
      true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules"]
}

target — Which JavaScript version to compile down to. Options: "ES5", "ES6", "ES2020", "ESNext". Analogy: "Should the darbar's decrees be written in ancient Persian or modern Urdu?" If you're targeting older browsers, use ES5. For modern Node.js, ES2020 or ESNext works great.

module — Which module system to use. "commonjs" for Node.js (require/module.exports), "ESNext" for browsers and bundlers (import/export). outDir — Where compiled JS files go ("./dist"). rootDir — Where your TS source lives ("./src"). strict — Enables ALL strict type-checking options at once. We'll deep dive into this in 8.2!

esModuleInterop — Allows importing CommonJS modules with import syntax naturally. Without it, import express from 'express' might fail. skipLibCheck — Skips type checking of .d.ts files in node_modules, speeding up compilation significantly. forceConsistentCasingInFileNames — Ensures file name casing is consistent, which prevents bugs when deploying to Linux from a Windows machine.

03include & exclude

TypeScript needs to know WHICH files to compile. It can't just guess — you have to tell it explicitly through include, exclude, and files. Getting this right keeps your builds clean and fast, avoiding the nightmare of accidentally compiling test files or node_modules.

include — Glob patterns for files to include:

"include": [
  "src/**/*"
]

The **/* means "all files in all subdirectories." So src/**/* captures every .ts file inside src/ and its nested folders. This is the most common pattern — you want everything in your source folder compiled.

exclude — Glob patterns for files to skip:

"exclude": [
  "node_modules",
  "dist",
  "**/*.test.ts"
]

files — Explicit list of individual files (used instead of include for small projects):

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

Precedence: files > exclude > include. If a file matches both include and exclude, exclude WINS. The file will be skipped. Note that node_modules is excluded by default — you don't strictly need to add it, but many developers do for clarity and documentation purposes.

rootDir interaction: If rootDir is "src" and you include files outside it (like a scripts/setup.ts at the project root), the directory structure in outDir may not match what you expect. Keep all your compiled source under rootDir to maintain a clean output structure. Project references (references) are an advanced feature for monorepos — we'll mention them but won't dive deep here.

04tsconfig Traps

tsconfig.json seems simple, but it has traps that have caused countless hours of debugging for developers. Knowing these will save you from mysterious build failures and weird runtime behavior.

Trap 1: Missing tsconfig

// Without tsconfig, running `tsc` compiles
// EVERYTHING in the current directory
// with LOOSE defaults. Chaos!

// ALWAYS create one:
tsc --init

The tsc --init command generates a starter tsconfig with all options commented out — perfect starting point!

Trap 2: target ≠ module

// WRONG thinking:
// "target is ES2020 so module must be
//  ESNext too"

// RIGHT: they're INDEPENDENT!
{
  "target": "ES2020",
  "module": "commonjs"
  // Modern JS syntax + Node require()
  // Very common for Node.js projects!
}

target is the JS SYNTAX version (arrow functions, optional chaining). module is the MODULE SYSTEM (import vs require). They control completely different things!

Trap 3: outDir same as source

// DANGER! .js files next to .ts files
{
  "outDir": "./src",  // Messy!
  "rootDir": "./src"
}

// RIGHT: separate output folder
{
  "outDir": "./dist",
  "rootDir": "./src"
}

Compiling into your source folder creates .js files right next to your .ts files. When you import, you might accidentally import the compiled version! Always use a separate outDir.

Trap 4: Forgetting include/exclude — Without them, tsc might try to compile scripts in node_modules, build folders, or random config files. Always specify what to include and exclude.

Trap 5: Comments in JSON — tsconfig.json is actually parsed as JSON5, which allows // comments. But some external tools (ESLint, Prettier) might break when they encounter comments. Use with caution.

05tsconfig Essentials Cheatsheet

Here's your complete cheatsheet for tsconfig.json essentials. Pin this to your mental whiteboard — every TypeScript project you create will need these settings.

Creation:

tsc --init

Must-Know Options:

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames":
      true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

Quick Reference:

target — JS syntax version (ES5, ES2020, ESNext)
module — Module system (commonjs, esnext)
outDir — Compiled JS output folder
rootDir — TS source root folder
strict — Enable all strict checks
esModuleInterop — CJS import compatibility
skipLibCheck — Faster builds

Key Rules:

Always have a tsconfig — never rely on defaults
target ≠ module — they're independent settings
Use separate outDir — never compile into source
Exclude node_modules and test files
Use tsc --init as your starting point

The Golden Rule: tsconfig.json is the Nizam's darbar rulebook — without it, the compiler runs wild. Set the rules, enforce the protocols, and your kingdom will prosper, bhai!

Key Points

tsconfig.json controls how the TypeScript compiler behaves — the project's rulebook
target sets the JS syntax version, module sets the module system — they are independent
Always use separate outDir and rootDir — never compile into your source folder
include and exclude control which files get compiled — exclude wins over include
Use tsc --init to generate a starter config, then customize it for your project

Previous7.7 — Template Literal Types 📋 All Chapters Next Chapter8.2 — Strict Mode Deep Dive →