typescript-strict

TypeScript Strict Mode

Every any is a runtime bug that the compiler was ready to catch and was told not to. Strict TypeScript converts a class of production failures - undefined access, wrong-shape API responses, unhandled union cases - into compile errors that cost seconds instead of incidents. This skill enforces strictness in new code and migrates existing loose codebases without a big-bang rewrite.

Operating procedure

1. Determine the mode. Greenfield code: apply the full config and the banned/required patterns below from the first commit. Existing loose codebase: jump to the migration procedure - do not flip every flag at once, because a wall of 2,000 errors gets the whole effort reverted.
2. Set the config. The target tsconfig is the artifact below. "strict": true is the floor, not the ceiling - noUncheckedIndexedAccess and exactOptionalPropertyTypes catch real bugs that strict alone misses.
3. Write to the banned/required pattern lists. Every review comment and every fix should cite one of them.
4. Prefer narrowing over asserting. When the compiler complains, the question is "how do I prove this to the compiler," not "how do I silence it." Use the narrowing toolkit.
5. Contain unavoidable casts with the escape-hatch policy. A cast is a claim the compiler cannot check; isolate it, validate it, and never let it propagate.

Inputs to collect

Before migrating or reviewing, gather: (1) the current tsconfig, (2) whether the codebase is greenfield or existing - and if existing, the error count per flag (tsc --noEmit after toggling each flag tells you), (3) any third-party libraries with missing or bad types, since those are where casts concentrate. If the error counts are unknown, measure them first; label any estimate a guess.

Target tsconfig

{
  "compilerOptions": {
    "strict": true,                        // enables all strict-family checks
    "noUncheckedIndexedAccess": true,      // arr[i] and obj[key] are T | undefined
    "exactOptionalPropertyTypes": true,    // { a?: string } rejects { a: undefined }
    "noImplicitOverride": true,
    "noImplicitReturns": true,
    "noFallthroughCasesInSwitch": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "forceConsistentCasingInFileNames": true
  }
}

Banned patterns

• any - use unknown and narrow, or define the type.
• as SomeType on values from outside the type system - use type guards or schema validation instead.
• value!.property non-null assertion - handle null/undefined explicitly.
• @ts-ignore - fix the error. If suppression is truly unavoidable, @ts-expect-error with a reason comment, which errors when the underlying problem is fixed.
• Implicit any in function parameters.

Required patterns

• Explicit return types on exported/public functions.
• unknown over any for truly unknown data, then narrow.
• satisfies over as when checking a value against a type without widening it.
• Discriminated unions over bags of optional properties.
• as const assertions for literal types.
• Exhaustive switches with a never check in the default case.

Good/bad pairs

Bad - any erases checking downstream:

function parse(json: string): any { return JSON.parse(json) }
const user = parse(body); user.emial // typo compiles, crashes later

Good - unknown forces proof before use:

function parse(json: string): unknown { return JSON.parse(json) }
const data = parse(body)
if (isUser(data)) { data.email } // typo is a compile error

Bad - assertion claims without evidence:

const user = JSON.parse(body) as User // wrong shape crashes at runtime

Good - narrowing proves the shape:

function isUser(x: unknown): x is User {
  return typeof x === 'object' && x !== null && 'id' in x && 'email' in x
}

Good - exhaustive switch that breaks the build when a variant is added:

function handle(action: Action) {
  switch (action.type) {
    case 'A': return handleA(action)
    case 'B': return handleB(action)
    default: { const _exhaustive: never = action; throw new Error('unreachable') }
  }
}

Migration procedure for a loose codebase

Order matters: each flag builds on the previous one's guarantees, and the noisiest flags come last so early wins build momentum.

1. Ban new violations first: turn on the target flags in CI for new and changed files only (lint rule or a diff-based check), so the hole stops getting deeper while you drain it.
2. Enable noImplicitAny. Fix by adding real types, not : any. This is the highest-value flag per error fixed.
3. Enable strictNullChecks (with strictFunctionTypes and alwaysStrict). Usually the largest error count. If a flag produces more errors than the team can fix in about two weeks, scope it per-directory with project references or a second tsconfig, and ratchet the boundary weekly - never let an "errors allowed" list grow.
4. Enable the remainder of the strict family (strictBindCallApply, strictPropertyInitialization, useUnknownInCatchVariables), then replace the individual flags with "strict": true.
5. Enable noUncheckedIndexedAccess, then exactOptionalPropertyTypes. These are last because they are the noisiest and the fixes (index checks, undefined-vs-absent distinctions) are mechanical once the codebase is null-safe.
6. Delete every @ts-expect-error you can after each step; each one still standing needs a reason comment.

Escape-hatch policy

A cast is acceptable only at a boundary the type system cannot see across: deserialized JSON, a third-party library with wrong types, a test fixture. Contain it:

• One cast per boundary, inside a single adapter function that validates before asserting (type guard or schema check). Callers receive a real type and never see the cast.
• Comment every cast with the reason it is safe.
• as unknown as T double assertions only in test code, never in production paths.
• @ts-expect-error over @ts-ignore, always with a description.

Deliverable

Produce strict-compliant code plus, for migrations, a flag-by-flag plan: current error count per flag, the enablement order above, the per-directory scoping if any count exceeds the two-week budget, and the CI ratchet that blocks new violations immediately.

Do NOT

• Do not fix a strict error by widening a type to any or adding ! - that converts a found bug back into a hidden one.
• Do not flip all flags at once on a large codebase; the resulting error wall gets the migration reverted.
• Do not allow a suppression list that can grow; ratchets only tighten.
• Do not use as to satisfy the compiler on data from outside the process - validate, then narrow.
• Do not skip noUncheckedIndexedAccess because it is noisy; unchecked index access is the single most common strict-mode blind spot.

Quality bar

• tsc --noEmit passes with the target config (or the migration plan states exactly which flags are pending and their error counts).
• Zero any, zero @ts-ignore, zero bare non-null assertions in the changed code.
• Every remaining cast sits inside a validating adapter with a reason comment.
• Every switch over a union has a never exhaustiveness check.
• Public functions declare their return types.