TypeScript Tsconfig Options
Quick reference for the most important tsconfig.json options to configure your TypeScript projects.
TL;DR
- 01Use strict mode to catch the most type-related bugs.
- 02Set target and module to match your runtime environment.
- 03Configure include and exclude to control compiled files.
Tips
- 01Start every new project with <code>"strict": true</code>, since adding it later means fixing many type errors at once.
Warnings
- 01Changing <code>"target"</code> or <code>"module"</code> mid-project can break your bundler, so update one setting at a time and test.
Getting Started
- Generate a starter file by running the compiler with the init flag.
tsc --init - The
tsconfig.jsonfile sits at the root of your TypeScript project. - All compiler options live under the
"compilerOptions"key.{ "compilerOptions": { "strict": true } } - Run
tscwith no arguments to compile using these settings. - Use
tsc --noEmitfor type-checking only without writing files.
Strict Mode
- Enable
"strict": trueto turn on all strict checks at once.{ "compilerOptions": { "strict": true } } - Strict mode includes
noImplicitAny,strictNullChecks, and several others. - Use
"strictNullChecks"to require explicit handling of null and undefined. - Use
"noImplicitAny"to flag variables that have no type annotation. - Strict mode is the recommended baseline for every new project.
Target and Module
- Use
"target"to choose the JavaScript version of the compiled output.{ "compilerOptions": { "target": "ES2022" } } - Pick
"ES2022"or newer for modern browsers and current Node versions. - Use
"module"to choose between ESM, CommonJS, or bundler modules.{ "compilerOptions": { "module": "ESNext" } } - Use
"lib"to include type definitions for browser APIs or other globals. - These settings determine what features your compiled code can use.
Paths and Includes
- Use
"include"and"exclude"to control which files are compiled.{ "include": ["src/**/*"], "exclude": ["node_modules", "dist"] } - Use
"outDir"to choose where compiled JavaScript files are saved. - Use
"rootDir"to set the root folder of your TypeScript source files. - Set up path aliases with
"baseUrl"and"paths"for cleaner imports.{ "compilerOptions": { "baseUrl": "./src", "paths": { "@/*": ["*"] } } } - Path aliases require both
tsconfig.jsonand your bundler to agree.
Helpful Extras
- Enable
"sourceMap": trueto generate source maps for easier debugging.{ "compilerOptions": { "sourceMap": true } } - Use
"esModuleInterop": truefor cleaner imports from CommonJS modules. - Set
"skipLibCheck": trueto skip type checking of declaration files. - Use
"resolveJsonModule": trueto import JSON files directly in code. - Use
"jsx": "preserve"for React projects that use a separate bundler.
FAQ
The 'strict' flag enables a group of checks including 'strictNullChecks', 'noImplicitAny', 'strictFunctionTypes', and others. Enabling it together is more reliable than toggling individual flags, since some checks depend on others being active.
Use the 'include' array to specify which directories or globs TypeScript should compile, and 'exclude' to block specific paths like 'node_modules' or 'dist'. Without 'include', TypeScript compiles every .ts file it finds from the project root.
'target' controls the JavaScript syntax version TypeScript outputs (e.g. ES2020), while 'module' controls how imports and exports are emitted (e.g. CommonJS vs ESNext). They are independent—you can target ES5 syntax while still emitting ESNext modules.
Add a 'paths' mapping under 'compilerOptions' and set 'baseUrl' to your project root. Note that TypeScript only handles type resolution—your bundler (Webpack, Vite, etc.) needs its own alias config to resolve these paths at runtime.
TypeScript only uses the nearest tsconfig.json relative to the file being compiled, so nested configs can shadow parent ones. Also, running 'tsc' directly without a file argument reads tsconfig.json, but passing a file explicitly (e.g. 'tsc index.ts') bypasses it entirely.