TypeScript tsconfig.json Cheatsheet — 55+ Compiler Options with Defaults and Examples

Umbrella flag that enables seven strict checks at once: noImplicitAny, strictNullChecks, strictFunctionTypes, strictBindCallApply, strictPropertyInitialization, noImplicitThis, and useUnknownInCatchVariables. Start every new project with this. Migrate existing projects incrementally using `// @ts-nocheck` on noisy files.

"strict": true

⚠ Pitfall Enabling strict on a large existing codebase can produce thousands of errors at once. Use `// @ts-nocheck` at the top of noisy files while migrating, rather than suppressing every error individually.

Raises an error when TypeScript would infer `any` due to missing type information. The most common trigger is an un-annotated function parameter — `function foo(x)` becomes an error, forcing you to write `function foo(x: string)`.

"noImplicitAny": true

Makes `null` and `undefined` their own distinct types instead of being assignable to every type. Without this flag, forgetting to handle null is a silent bug. With it, you must explicitly narrow with checks, use the non-null assertion (`!`), or include `null` in a union type.

"strictNullChecks": true

⚠ Pitfall The most common migration error is forgetting to add `| null | undefined` to return types of functions that can return nothing.

Enforces contravariance for function parameter types in callback positions. Catches bugs where you pass a function that accepts a narrower type than the callback expects. Note: method declarations (not arrow functions) remain bivariant for compatibility.

"strictFunctionTypes": true

Enables stricter checking of arguments passed to `bind`, `call`, and `apply`. Without this, these methods accept `any` arguments regardless of the function signature.

"strictBindCallApply": true

Raises an error for class properties that are declared but not initialized in the constructor. Requires `strictNullChecks`. Use the definite assignment assertion (`!`) only when you genuinely control initialization order outside the constructor (e.g. dependency injection).

"strictPropertyInitialization": true

⚠ Pitfall Don't prefix every property with `!` to silence the error — that defeats the purpose. Use it only for properties initialized in lifecycle hooks or injected by a framework.

Raises an error when `this` has an implicit `any` type, which typically occurs in standalone functions and object literals where TypeScript can't determine the type of `this`. Fix by adding a `this: ClassName` parameter to the function signature.

"noImplicitThis": true

Makes caught variables in `catch` clauses typed as `unknown` instead of `any`. Forces you to narrow the type before accessing it — safer because `throw` can throw any value, not just `Error` instances.

"useUnknownInCatchVariables": true

⚠ Pitfall Use `if (error instanceof Error)` or a type guard. Casting directly to `Error` without a check is unsafe — `throw "a string"` is valid JavaScript.

Reports errors for local variables that are declared but never read. Prefix intentionally unused variables with `_` (e.g. `_index` in a callback) to suppress the error without removing them.

"noUnusedLocals": true

Reports errors for function parameters that are declared but never used. Like `noUnusedLocals`, prefix with `_` to mark intentionally unused parameters.

"noUnusedParameters": true

Reports an error when not all code paths in a non-void function have a `return` statement. Prevents the classic "forgot a return in the else branch" bug in complex if/else chains.

"noImplicitReturns": true

Reports an error for any non-empty `case` in a switch statement that falls through to the next case without a `break`, `return`, or `throw`. Empty cases (a series of `case X: case Y:`) are still allowed.

"noFallthroughCasesInSwitch": true

Differentiates between "property is absent" and "property is set to undefined". An optional property `x?: string` allows `obj.x = "foo"` or omitting `x` entirely, but NOT `obj.x = undefined`. This is the most accurate model of optional properties.

"exactOptionalPropertyTypes": true

⚠ Pitfall Many codebases use `obj.x = undefined` to "unset" a property. With this flag you must use `delete obj.x` instead, or change the type to `x?: string | undefined`.

Adds `undefined` to array index access and index signature access return types. Since `arr[5]` may be out of bounds, TypeScript requires `arr[5] !== undefined` checks before use. Catches a very common class of runtime errors.

"noUncheckedIndexedAccess": true

⚠ Pitfall This flag is NOT enabled by `strict` — you opt in manually. It can be very noisy in array-heavy code. Where you are certain the index exists, use `arr[i]!` (non-null assertion).

Requires bracket notation (`obj["key"]`) instead of dot notation (`obj.key`) when accessing a property defined via an index signature. Makes it visually clear which accesses are "safe" (declared) vs "dynamic" (index signature).

"noPropertyAccessFromIndexSignature": true

Controls what module format TypeScript emits. `"CommonJS"` generates `require()`/`module.exports` (Node.js classic). `"ESNext"` generates `import`/`export` (for bundlers). `"NodeNext"` enables full Node.js ESM with `.js` extensions required in imports.

"module": "NodeNext"

⚠ Pitfall For Vite/webpack: use `"ESNext"` + `"moduleResolution": "bundler"`. For Node.js ESM: use `"NodeNext"` for both `module` and `moduleResolution`. Never mix `"ESNext"` module with `"node10"` resolution.

Determines how TypeScript locates module files. `"bundler"` (TS 5.0+) matches modern bundlers like Vite/esbuild — no file extensions required. `"NodeNext"` mirrors Node.js 12+ resolution, requiring `.js` extensions. `"node10"` is the legacy Node.js resolution strategy.

"moduleResolution": "bundler"

Allows importing `.json` files with automatic type inference based on the JSON structure. Very useful for importing config files, locale strings, or static data sets directly into TypeScript.

"resolveJsonModule": true

⚠ Pitfall Large JSON files are fully type-checked and bundled, which can slow compilation and increase bundle size. For very large data files, consider loading them at runtime.

Allows imports of `.ts`, `.tsx`, and `.mts` files with their explicit extensions in `import` statements. Requires `noEmit` or `emitDeclarationOnly` to be enabled, since TypeScript cannot handle `.ts` extensions in emitted JavaScript.

"allowImportingTsExtensions": true

Lets TypeScript process `.js` and `.jsx` files alongside `.ts`. Useful when incrementally migrating a JavaScript project — you can convert one file at a time without renaming everything.

"allowJs": true

Enables type checking in `.js` files (requires `allowJs`). TypeScript uses type inference and JSDoc annotations to check JavaScript. A great starting point when adopting TypeScript in a JS codebase before adding explicit type annotations.

"checkJs": true

Enforces `import type` for type-only imports and `export type` for type-only exports. Errors if you import a type without the `type` keyword. Ensures type imports are stripped at compile time without needing Babel or other tools. Replaces `importsNotUsedAsValues`.

"verbatimModuleSyntax": true

⚠ Pitfall You will need to add `type` to all existing type-only imports — `import { Foo }` becomes `import type { Foo }`. Most editors can auto-fix this with a quick action.

Controls how TypeScript determines whether a file is a module or a script. `"auto"`: a file is a module if it contains `import`/`export` or `import.meta`. `"force"`: every non-declaration file is treated as a module — useful to prevent accidental global declarations.

"moduleDetection": "force"

Sets the JavaScript language version TypeScript emits. Modern projects should use `"ES2022"` or `"ESNext"`. Affects both syntax transforms (async/await, optional chaining) and which built-in types are available via `lib`. A mismatch between `target` and actual runtime can cause subtle failures.

"target": "ES2022"

⚠ Pitfall Setting `target` higher than your actual runtime supports causes runtime errors. For example, `"ES2022"` on Node 12 will fail for methods like `Array.at()` that were added later.

Specifies built-in API type definitions to include. When omitted, TypeScript automatically includes a lib set based on `target`. Common additions: `"DOM"` for browser APIs, `"DOM.Iterable"` for iterable DOM collections. Omit `"DOM"` in Node.js projects to avoid browser-type bleed.

"lib": ["ES2022", "DOM", "DOM.Iterable"]

Specifies the output directory for compiled files. TypeScript mirrors the source directory structure inside `outDir`. Combine with `rootDir` for predictable output layout. Add `outDir` to `.gitignore`.

"outDir": "./dist"

Specifies the root of your TypeScript source files. Used with `outDir` to compute output paths — the directory structure under `rootDir` is replicated under `outDir`. Set explicitly to `"./src"` if TypeScript infers it incorrectly.

"rootDir": "./src"

Emits `.d.ts` declaration files alongside the compiled `.js`. Required when publishing a TypeScript library so consumers get type information. Combine with `emitDeclarationOnly` to generate types without JavaScript.

"declaration": true

Emits `.d.ts.map` source map files alongside `.d.ts` files. Allows editors to "Go to Definition" in the original `.ts` source instead of the generated `.d.ts`. Greatly improves the developer experience for library consumers who have the source available.

"declarationMap": true

Emits `.js.map` source map files that map compiled JavaScript back to the original TypeScript. Enables debuggers and error reporting tools (Sentry, etc.) to show TypeScript line numbers instead of compiled JavaScript. Essential for production debugging.

"sourceMap": true

Runs the type checker but does not write any output files to disk. Ideal when a bundler (Vite, esbuild, webpack) handles compilation — TypeScript is used only for type checking. Pair with `isolatedModules: true` for the fastest type-check pass.

"noEmit": true

Emits only `.d.ts` type declaration files, not `.js` files. The perfect setup when publishing a library: TypeScript generates types via `tsc`, the bundler generates JavaScript. Requires `declaration: true`.

"emitDeclarationOnly": true

Strips all comments from the emitted JavaScript. Does not affect `.d.ts` declaration files. Useful when your TypeScript source is heavily commented with JSDoc but you want a lean output bundle. Triple-slash reference directives (`/// <reference>`) are always preserved.

"removeComments": true

Imports helpers (`__awaiter`, `__extends`, `__assign`, etc.) from `tslib` instead of inlining them in every compiled file. When many files use the same helpers, this reduces overall bundle size. Requires `tslib` as a dependency.

"importHelpers": true

Enables correct iteration over iterables (for...of, spread, destructuring) when compiling to ES5 or ES3 targets. Without it, TypeScript uses a simpler but incorrect implementation. Use `importHelpers: true` with `tslib` to avoid inlining the iterator helper in every file.

"downlevelIteration": true

Enables interoperability between CommonJS and ES module `import` syntax. Without it, `import React from "react"` fails for modules that export only `module.exports` (no `.default` property). With it, TypeScript adds helper code so default imports work for CJS modules. Automatically enables `allowSyntheticDefaultImports`.

"esModuleInterop": true

⚠ Pitfall This adds runtime helper functions (`__importDefault`, `__importStar`). Use `importHelpers: true` with `tslib` to import them once rather than duplicating them in each file.

Allows `import Foo from 'module'` when the module doesn't explicitly export a default. This is type-checking only — it emits no runtime code. When `esModuleInterop` is on, this is set automatically. If you also need runtime behavior, use `esModuleInterop`.

"allowSyntheticDefaultImports": true

Ensures each file can be safely transpiled in isolation without type information from other files. Required when using Babel, esbuild, or SWC to compile TypeScript. Raises errors for things that only work with full type info: `const enum`, non-type re-exports, and ambient module declarations.

"isolatedModules": true

⚠ Pitfall `const enum` is completely disallowed — switch to regular `enum` or a const object. Use `import type` for all type-only imports to ensure correct stripping.

Requires all imports to use the exact casing of the referenced file name. Prevents bugs that only appear on case-sensitive filesystems (Linux) but not on case-insensitive ones (macOS, Windows). Catches `import Foo from "./foo"` when the file is actually `Foo.ts`.

"forceConsistentCasingInFileNames": true

Skips type checking of all `.d.ts` declaration files (yours and those from npm packages). Prevents errors from incorrect or conflicting third-party type definitions that you cannot fix. Significantly speeds up compilation. Recommended in almost every application.

"skipLibCheck": true

⚠ Pitfall This also skips checking your own `.d.ts` files. If you maintain a library, keep `skipLibCheck: false` in the library's tsconfig but use `true` in consumer apps.

Enables support for the legacy decorator syntax (Stage 2 decorators, TypeScript's original implementation). Required for Angular, NestJS, TypeORM, and other frameworks that use `@Decorator` syntax. Note: TypeScript 5.0 added support for the official TC39 decorator standard separately.

"experimentalDecorators": true

Emits design-time type metadata for declarations that have decorators. Required for dependency injection containers that use reflection (NestJS, InversifyJS). Requires `experimentalDecorators: true` and the `reflect-metadata` polyfill at runtime.

"emitDecoratorMetadata": true

Controls how JSX syntax is transformed. `"react-jsx"` (React 17+): uses the automatic runtime, no need to import React. `"react"` (legacy): requires `import React from "react"` in every JSX file. `"preserve"`: leaves JSX for the bundler. `"react-native"`: like preserve but outputs `.js` extension.

"jsx": "react-jsx"

Specifies the module that provides `jsx` and `jsxs` factory functions when using `"jsx": "react-jsx"`. Set to `"preact"` for Preact, `"solid-js"` for SolidJS, `"vue"` for Vue 3, etc. Can be overridden per-file with `/** @jsxImportSource preact */`.

"jsxImportSource": "preact"

Specifies the function to use for JSX element creation when using `"jsx": "react"` (the legacy transform). Change to `"h"` for Preact, `"React.createElement"` is the React default. This is irrelevant when using the new `"react-jsx"` transform.

"jsxFactory": "h"

Sets the base directory for resolving non-relative module names. Set to `"."` (project root) or `"./src"` to enable bare imports like `import Button from "components/Button"` instead of `"../../components/Button"`. Usually paired with `paths`.

"baseUrl": "."

⚠ Pitfall TypeScript handles type resolution only. Your bundler (Vite `resolve.alias`, webpack `resolve.alias`) must also be configured with matching paths for the imports to work at runtime.

Maps module name patterns to locations. Enables path aliases like `@/*` → `./src/*`. Each pattern maps to an array of fallback locations. Requires `baseUrl` to be set.

"paths": { "@/*": ["./src/*"] }

⚠ Pitfall `paths` is type-checking only — TypeScript will not rewrite import paths in emitted files. Configure matching aliases in your bundler for runtime resolution.

Tells TypeScript to treat multiple directories as if they were merged into a single virtual root. Useful in monorepos or build systems where files from multiple directories are combined at runtime. Allows relative imports between these directories.

"rootDirs": ["./src", "./generated"]

Enables project references, allowing `tsc --build` to rebuild only the changed packages in a multi-package repository. Requires `declaration: true` and creates a `.tsbuildinfo` cache file. The cornerstone of TypeScript monorepo incremental builds.

"composite": true

Saves build information to a `.tsbuildinfo` file so subsequent builds can skip recompiling unchanged files. Significantly speeds up TypeScript compilation in large projects. Add `.tsbuildinfo` to `.gitignore`.

"incremental": true

Specifies the path for the `.tsbuildinfo` incremental build cache file. Change this when building multiple tsconfigs that might write to the same default location, or when storing the cache in a CI-specific directory.

"tsBuildInfoFile": "./.tsbuildinfo"