The tsconfig.json Configuration
Configure the TypeScript compiler with tsconfig.json: target, strict, paths, and more.
What you'll learn
- The essential tsconfig.json options: target, module, and lib
- How strict mode enables a bundle of safety checks
- Path aliases with baseUrl and paths for cleaner imports
- Project references and composite projects for monorepos
Concept
Core Options
The tsconfig.json file configures the TypeScript compiler. The most important options are target (the JavaScript version to compile to, e.g. es2020), module (the module system, e.g. esnext or commonjs), and lib (which built-in APIs are available, e.g. ["es2020", "dom"]). outDir specifies where compiled JavaScript goes, and rootDir specifies where source files live.
Strict Mode
The strict: true flag enables a bundle of safety checks: strictNullChecks (null/undefined are not assignable to other types), noImplicitAny (parameters must have types or be inferable), strictFunctionTypes, strictBindCallApply, strictPropertyInitialization, noImplicitThis, and alwaysStrict. Enabling strict is the single best decision for a new TypeScript project — it catches the most bugs with the least effort.
Path Aliases and References
Path aliases (paths) let you import with absolute paths instead of long relative ones: import { User } from "@models/user" instead of ../../../models/user. You configure them with baseUrl and paths in tsconfig. Project references (references with composite: true) let you split a large project into smaller sub-projects that compile independently, which is essential for monorepo performance.
Example
// tsconfig.json — a modern, strict configuration.
{
"compilerOptions": {
"target": "es2020",
"module": "esnext",
"moduleResolution": "bundler",
"lib": ["es2020", "dom"],
// Strict mode — enables all safety checks.
"strict": true,
"noUnusedLocals": true,
"noUnusedParameters": true,
"noFallthroughCasesInSwitch": true,
// Output.
"outDir": "./dist",
"rootDir": "./src",
"declaration": true,
"sourceMap": true,
// Path aliases for clean imports.
"baseUrl": "./src",
"paths": {
"@models/*": ["models/*"],
"@utils/*": ["utils/*"],
"@components/*": ["components/*"]
},
// Module resolution.
"esModuleInterop": true,
"skipLibCheck": true,
"forceConsistentCasingInFileNames": true
},
"include": ["src/**/*"],
"exclude": ["node_modules", "dist"]
}
tsconfig.json controls the compiler. target sets the JS version, strict enables safety checks, paths creates import aliases. Always enable strict for new projects — it catches the most bugs.
Try it
- Code Minifier
The target setting determines which JS features get transpiled down.
- Code Diff
Compare compiled output across different target settings.
Common mistakes
The mistake
Disabling strictNullChecks or strict to avoid fixing type errors
The fix
Keep strict enabled. The errors it surfaces are real bugs. Fix the code rather than weakening the compiler. The short-term pain prevents long-term runtime errors.
The mistake
Setting target too low and losing modern JavaScript features
The fix
Set target to match your runtime environment (es2020 for modern browsers/Node). A too-low target transpiles features unnecessarily, producing larger and slower output.
Practice The tsconfig.json Configuration
1 exercise
Look up unfamiliar terms
A beginner-friendly glossary explains jargon in plain English — variables, functions, DOM, Promise, and more.
Build real projects
Apply what you learned by building guided projects with starter code and solutions.
Decode error messages
Plain-English explanations of common errors — what they mean, why they happen, and how to fix them.