Skip to content
Tutorials Center
My learning

Topics

TypeScript Reference ยท tsconfig: Type Checking Options

TypeScript strictNullChecks option

Reference for strictNullChecks in TypeScript: how null and undefined become separate types, the errors it reports, and the idioms to narrow them safely.

With strictNullChecks on, null and undefined are their own types and are no longer members of every other type. A string is always a string; a value that may be missing is string | null or string | undefined, and the compiler makes you handle the missing case before using it. This removes the most common runtime error in JavaScript, "cannot read properties of undefined".

With the flag off (the old default), null and undefined are assignable to everything, so the compiler cannot warn about them at all. The flag is part of strict.

TypeScript
let name: string = null;          // error: Type 'null' is not assignable to type 'string'.
let maybe: string | null = null;  // fine

Try it

TypeScript The compiler stops a possible null

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.

TypeScript Handling absence on purpose

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.

Syntax

JSON
{ "compilerOptions": { "strictNullChecks": true } }
TEXT
tsc --strictNullChecks
Situation Behavior with the flag on
let x: string = null Error: null is not assignable to string.
value.length on string | null Error: 'value' is possibly 'null' (TS18047), or 'value' is possibly 'undefined' (TS18048).
Optional parameters and properties (x?: T) Type is T | undefined.
Array.prototype.find, Map.get, regex match Return T | undefined or T | null; you must check.
Narrowing if (x), x !== null, x != null, typeof, optional chaining and ?? all remove the missing cases.

Edge cases: void is not the same as undefined for assignability in some positions; a function with return type void may return anything when it is a callback type. Also, strictNullChecks is required for many other features to behave sensibly, for example exactOptionalPropertyTypes.

Usage notes

  • Prefer narrowing to assertions. x! tells the compiler to trust you and is erased at runtime; a wrong ! still crashes.
  • == null is the one common use of loose equality: it matches both null and undefined.
  • Distinguish absent from empty. An empty string and 0 are falsy, so if (x) is wrong for numbers that can be zero; use x !== undefined.
  • Indexing arr[i] is not undefined-aware unless you add noUncheckedIndexedAccess.
  • Definite assignment !: (name!: string) on a class field promises a later assignment; see strictPropertyInitialization.
  • Migrating: enabling the flag late produces many errors at boundaries (JSON, DOM queries). Fix the types at the boundary, not at every use.
  • Library authors should declare T | undefined honestly; lying with non-null types shifts the crash to users.