Mastering tsconfig.json in TypeScript

When you work with TypeScript, there’s one file you’ll see in almost every project:

tsconfig.json.

At first glance, it looks like a boring JSON file filled with cryptic keys and values. But in reality, it’s the control center for your TypeScript project.

Think of it as your project’s rulebook:

• It tells TypeScript how to compile your code.
• It decides which files to include (and which to ignore).
• It controls where the compiled JavaScript will go.
• It can even make your code faster, cleaner, and safer.

By the end of this article, you’ll understand tsconfig.json from beginner basics to advanced pro tips — all in plain English.

---

Part 1: Beginner Level — The Essentials

When you run tsc (the TypeScript compiler) in a folder, it looks for tsconfig.json.

If it finds one, it uses the settings inside. If not, it uses defaults (which may not be what you want).

1. The compilerOptions Section

This is the most important part — it’s like telling TypeScript how to cook your code.

Common beginner-friendly settings:

• target – Which version of JavaScript you want.
  

  "target": "ES2020"
  

  Means: “Make my code modern and clean.”

• module – How your files talk to each other.
  

  "module": "CommonJS"
  

  CommonJS is great for Node.js; ESNext is for modern browsers.

• strict – Be picky about types and catch errors early.
  

  "strict": true
  

• outDir – Where to put compiled JavaScript files.
  

  "outDir": "./dist"
  

---

2. include and exclude

These decide which files TypeScript should look at.

• include – Files/folders to compile.
  

  "include": ["src"]
  

• exclude – Files/folders to ignore.
  

  "exclude": ["node_modules"]
  

---

✅ Beginner Example:

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

This is all you need to start most small projects.

---

Part 2: Intermediate Level — Getting More Control

Once you’re comfortable with the basics, you can use tsconfig.json to organize and simplify your project.

1. rootDir

Tells TypeScript where your source files are.

"rootDir": "./src"

Keeps your compiled files and source files nicely separated.

---

2. Path Aliases (baseUrl & paths)

Tired of writing "../../../utils/math"?

You can create shortcuts.

"baseUrl": "src",
"paths": {
  "@utils/*": ["utils/*"]
}

Now you can import like:

import { add } from "@utils/math";

---

3. Type Declarations

If you’re making a library, you can automatically create .d.ts files so others get type support.

"declaration": true

---

✅ Intermediate Example:

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "strict": true,
    "rootDir": "./src",
    "outDir": "./dist",
    "baseUrl": "src",
    "paths": {
      "@utils/*": ["utils/*"]
    },
    "declaration": true},
  "include": ["src"]
}

---

Part 3: Advanced Level — Performance & Multi-Project Builds

For bigger projects or production apps, tsconfig.json can do a lot more.

1. Speed Up Builds

• incremental – Saves compile info to speed up future builds.
  

  "incremental": true
  

• watch – Automatically recompiles when files change.
  

  tsc --watch
  

---

2. Multi-Project Workspaces

Large projects often have multiple tsconfig.json files:

• One root config.
• Separate configs for each module or package.

{
  "files": [],
  "references": [
    { "path": "./packages/core" },
    { "path": "./packages/utils" }
  ]
}

Run:

tsc --build

TypeScript will compile everything in the right order.

---

3. Strictness Tweaks

You can fine-tune strictness for different parts of your project:

"noImplicitAny": true,
"strictNullChecks": true

This is useful if you want strict rules in production code but looser rules in test files.

---

Level	Purpose	Common Settings	Example
Beginner	Just enough to compile TypeScript and keep things clean.	- target – JS version output.- module – Module system.- strict – Type safety.- outDir – Where compiled files go.- include & exclude – Control which files are compiled.	json\n{\n "compilerOptions": {\n "target": "ES2020",\n "module": "CommonJS",\n "strict": true,\n "outDir": "./dist"\n },\n "include": ["src"],\n "exclude": ["node_modules"]\n}\n
Intermediate	Better project organization & cleaner imports.	- All Beginner settings.- rootDir – Organize source code.- baseUrl & paths – Path aliases.- declaration – Generate .d.ts files for libraries.	json\n{\n "compilerOptions": {\n "target": "ES2020",\n "module": "ESNext",\n "strict": true,\n "rootDir": "./src",\n "outDir": "./dist",\n "baseUrl": "src",\n "paths": {\n "@utils/*": ["utils/*"]\n },\n "declaration": true\n },\n "include": ["src"]\n}\n
Advanced	Large projects, performance boosts, & multi-project setups.	- All Intermediate settings.- incremental – Faster builds.- watch – Auto-recompile.- composite & references – Multi-project builds.- Fine-grained strictness: noImplicitAny, strictNullChecks.	json\n{\n "compilerOptions": {\n "target": "ES2020",\n "module": "ESNext",\n "strict": true,\n "rootDir": "./src",\n "outDir": "./dist",\n "baseUrl": "src",\n "paths": {\n "@utils/*": ["utils/*"]\n },\n "declaration": true,\n "incremental": true,\n "noImplicitAny": true,\n "strictNullChecks": true\n },\n "include": ["src"],\n "references": [\n { "path": "./packages/core" },\n { "path": "./packages/utils" }\n ]\n}\n

Final Takeaways

• Start small: Just target, module, strict, outDir, include, and exclude are enough for beginners.
• Level up slowly: Add rootDir, aliases, and declarations as your project grows.
• Go advanced only when needed: Use incremental builds, multi-project configs, and strictness tuning for large-scale work.

tsconfig.json isn’t just a config file — it’s a map, a recipe, and a safety net all in one.

Learn it step by step, and it will save you hours of debugging, keep your project organized, and make your code run smoother.