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.
let name: string = null; // error: Type 'null' is not assignable to type 'string'. let maybe: string | null = null; // fine
Try it
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.
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
{ "compilerOptions": { "strictNullChecks": true } }
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. == nullis the one common use of loose equality: it matches bothnullandundefined.- Distinguish absent from empty. An empty string and
0are falsy, soif (x)is wrong for numbers that can be zero; usex !== undefined. - Indexing
arr[i]is notundefined-aware unless you addnoUncheckedIndexedAccess. - 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 | undefinedhonestly; lying with non-null types shifts the crash to users.