tsconfig.json Explained: strict Mode and the Compiler Options That Matter

tsconfig.json tells the TypeScript compiler which files belong to the project and how to check and compile them. There are over a hundred options, but a handful matter for almost every project.

A modern starting point#

{
  "compilerOptions": {
    "target": "es2022",
    "lib": ["es2023"],
    "module": "nodenext",
    "moduleResolution": "nodenext",
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "verbatimModuleSyntax": true,
    "skipLibCheck": true,
    "outDir": "dist",
    "rootDir": "src",
    "sourceMap": true
  },
  "include": ["src"]
}

For a front-end project built with a bundler (Vite, Next.js), typical differences are "lib": ["es2023", "dom", "dom.iterable"], "moduleResolution": "bundler", "jsx": "react-jsx" for React, and "noEmit": true (the bundler produces the JavaScript; tsc only type-checks).

strict#

"strict": true switches on a family of checks. It should be on in every new project:

Without strict mode, this compiles; with it, TypeScript catches the bug:

function greet(name) {
  return "Hello, " + name.toUpperCase();
}

error TS7006: Parameter 'name' implicitly has an 'any' type.

Migrating an old JavaScript project? Turn options on one at a time, but aim for full strict mode.

Extra safety options#

These are not part of strict but are worth considering:

noUncheckedIndexedAccess in action:

// with "noUncheckedIndexedAccess": true
const scores: number[] = [72, 95];
const first: number = scores[0];

error TS2322: Type 'number | undefined' is not assignable to type 'number'.

(The examples on this site are checked with strict; this block also enables noUncheckedIndexedAccess to show its effect.)

target and lib#

• target sets which JavaScript version is output. Syntax newer than the target is converted (for example, optional chaining to older checks). For modern browsers and Node.js, es2022 or later is typical.
• lib sets which built-in APIs TypeScript knows about. es2023 adds types for features like toSorted; dom adds document, window and HTMLElement. If TypeScript says a built-in method "does not exist", your lib may be too old.

Note that lib only provides types; it does not add the feature to old browsers.

module and moduleResolution#

See Modules and Imports.

Output options#

include, exclude and extends#

• include lists the files or folders to compile (["src"]); exclude removes some (such as test fixtures). node_modules is excluded by default.
• extends reuses another configuration. Shared base configs are published on npm, for example in the @tsconfig/ scope:

{
  "extends": "@tsconfig/node22/tsconfig.json",
  "compilerOptions": { "outDir": "dist" }
}

How the examples in this course are checked#

The code in this course is checked with --strict, target ES2022, the es2023 and dom libraries, nodenext modules and skipLibCheck, and @types/node for examples that use Node.js modules.

Practice#

{
  "compilerOptions": {
    "target": "es2022",
    "lib": ["es2023", "dom", "dom.iterable"],
    "module": "esnext",
    "moduleResolution": "bundler",
    "jsx": "react-jsx",
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "verbatimModuleSyntax": true,
    "skipLibCheck": true,
    "noEmit": true
  },
  "include": ["src"]
}

Key takeaway#