Strict Mode and tsconfig Deep Dive

Every example in the TypeScript for Beginners series has quietly depended on a tsconfig.json you may never have opened. This twentieth chapter of the 24-chapter series reads that file line by line: which options shape your program, which flags actually make up the strict family, how configuration scales to a large repository with project references, and how to migrate an inherited JavaScript config one flag at a time instead of in a single painful day.

Anatomy of tsconfig.json

TypeScript looks for tsconfig.json in the current folder and then in every folder above it, so one file at the repository root configures the whole tree. Six keys cover almost everything you will write:

A typical React application splits base options from app-specific ones:

{
  "extends": "./tsconfig.base.json",
  "compilerOptions": {
    "jsx": "react-jsx",
    "types": ["vite/client"]
  },
  "include": ["src", "vite.config.ts"],
  "exclude": ["node_modules", "dist"]
}

Expected output: npx tsc --showConfig prints the merged result, so you never have to guess what inheritance produced:

{
    "compilerOptions": {
        "target": "es2022",
        "module": "es6",
        "moduleResolution": "bundler",
        "jsx": "react-jsx",
        "strict": true
    },
    "include": ["src", "vite.config.ts"]
}

Two inheritance rules catch people out. include, exclude and files are not merged — the inheriting file replaces them wholesale — while relative paths written in the base file keep resolving against that base file, not against the config that extends it.

The options that shape your program

These are the flags you will meet in almost every codebase. Everything else is specialisation:

One pairing rule matters: moduleResolution: "bundler" only works with module set to preserve or es2015 and later — mix it with commonjs and you get error TS5095: Option 'bundler' can only be used when 'module' is set to 'preserve' or to 'es2015' or later. And isolatedModules has a sharp edge you will meet in real code: a type cannot be re-exported by value, so export { Course } from './models' reports error TS1205: Re-exporting a type when 'isolatedModules' is enabled requires using 'export type'. Bundlers translate one file at a time and cannot know that Course exists only at type level unless you say so.

The strict family

"strict": true is a bundle, not a single behaviour. It enables noImplicitAny, strictNullChecks, strictFunctionTypes, strictBindCallApply, strictPropertyInitialization, noImplicitThis, alwaysStrict and useUnknownInCatchVariables — the last two became part of the bundle as TypeScript matured, which is why older articles list a shorter set. Three flags you should often want are not included:

exactOptionalPropertyTypes is the subtlest of the three. Under it, assigning undefined to an optional property is rejected with error TS2375: Type '{ name: undefined; }' is not assignable to type 'User' with 'exactOptionalPropertyTypes: true'; if undefined is a genuine value, widen the declaration to name?: string | undefined and the intent is documented in the type itself.

Reading a real error report

Run npx tsc --noEmit on a project that has everything switched on and the output is one line per problem, in file order:

npx tsc --noEmit

Expected output:

src/profile.ts(6,24): error TS18048: 'user' is possibly 'undefined'.
src/profile.ts(10,17): error TS7006: Parameter 'role' implicitly has an 'any' type.
src/profile.ts(10,23): error TS6133: 'active' is declared but its value is never read.
src/profile.ts(11,9): error TS6133: 'theme' is declared but its value is never read.
src/profile.ts(18,15): error TS18046: 'err' is of type 'unknown'.
src/profile.ts(22,7): error TS2322: Type 'string | undefined' is not assignable to type 'string'.
  Type 'undefined' is not assignable to type 'string'.

Notice the shape: file(line,column), then a stable error code you can search for, then the message. Learning the handful of codes you see daily — TS2322, TS7006, TS18046, TS6133, TS2578 — turns a wall of red into a short checklist.

Project references for large repositories

When one repository holds several packages, checking everything from one config becomes slow and circular imports slip through. Project references split the work: each package is its own project, declares composite: true, and the root becomes a solution file that only lists references.

// root tsconfig.json
{ "files": [], "references": [{ "path": "./packages/core" }, { "path": "./packages/app" }] }

// packages/core/tsconfig.json
{
  "compilerOptions": { "composite": true, "declaration": true, "declarationMap": true, "outDir": "dist" },
  "include": ["src"]
}

Build the graph with the multi-project flag rather than plain tsc:

npx tsc -b

Expected output: silence and exit code 0 the first time; a second run prints nothing at all because packages/*/tsconfig.tsbuildinfo records that nothing changed. Change one file in core and only core and the projects referencing it are re-checked. The declaration maps also let your editor jump into the source behind a dependency instead of a generated .d.ts.

Migrating a configuration incrementally

If you inherit a JavaScript project, do not enable everything at once. Order matters, and each step should leave the build green:

1. Start checking without converting. Add "allowJs": true and "noEmit": true so .js and .ts files coexist while the bundler keeps emitting the JavaScript.
2. Choose files one at a time. Turn on "checkJs": true globally, or add // @ts-check at the top of a single file — a reviewed file reports errors while an untouched file stays quiet.
3. Enable noImplicitAny first. It is the highest-value flag per error, and every fix is an annotation you wanted to write anyway.
4. Then strictNullChecks. This produces the largest wave of errors; fix them with narrowing and guards, never with blanket assertions.
5. Add the optional flags — noUncheckedIndexedAccess, exactOptionalPropertyTypes, noUnusedLocals, noUnusedParameters — as separate commits so each diff is reviewable.
6. Flip "strict": true once the individual flags are on, then keep npx tsc --noEmit green in CI from that day forward (chapter 23 sets up the gate).

The destination is worth the climb: strict plus noUncheckedIndexedAccess is the configuration used by every example in the rest of this series.

Common mistakes

• Assuming strict covers everything — noUncheckedIndexedAccess and exactOptionalPropertyTypes are opt-in, so array-heavy code still slips through.
• Turning on strict and allowJs together on day one — you will drown in unrelated errors; migrate flag by flag, in the order above.
• Forgetting noEmit while a bundler builds the app — tsc then writes stale JavaScript next to your sources and tools start loading the wrong files.
• Leaving include too wide — a config without include also checks dist, scripts and fixtures, which is how “my build is suddenly slow” happens.
• Re-exporting types by value under isolatedModules — write export type, or the transpiler emits an import for something that does not exist at runtime.

Practice checklist

1. Run npx tsc --showConfig in your own project and match five printed options back to the file they came from.
2. Add noUncheckedIndexedAccess, read the first five errors, and fix them by narrowing rather than asserting.
3. Switch on noUnusedLocals and noUnusedParameters, then delete or underscore-prefix everything it flags.
4. Deliberately break a pairing — set moduleResolution to bundler with module: "commonjs" — and read TS5095 until it makes sense.
5. Split one repository into two projects with references and run npx tsc -b twice to see the second run do nothing.

What's next?

Your configuration now enforces the rules on purpose rather than by accident. Next you apply the same rigour to the one part of JavaScript that types cannot see: Error Handling and Result Types.