TypeScript Strict Mode (Deep Workflow)

Strictness is a gradient, not a single switch. The goal is fewer runtime surprises without blocking delivery—via incremental migration and clear typing boundaries at IO edges.

When to Offer This Workflow

Trigger conditions:

• Enabling strict, strictNullChecks, noImplicitAny, or noUncheckedIndexedAccess
• Legacy codebase full of any and @ts-ignore
• Runtime bugs that types would have caught (undefined, wrong shapes)
• Library authoring needing accurate .d.ts exports

Initial offer:

Use six stages: (1) baseline & goals, (2) compiler flags roadmap, (3) boundary typing, (4) narrowing & exhaustiveness, (5) generics & patterns, (6) verify & guardrails). Confirm TS version, build tool (tsc, esbuild, etc.), and monorepo layout.

Stage 1: Baseline & Goals

Goal: Know current pain and target strictness with metrics.

Actions

• Capture tsc --noEmit error count and top files by errors
• Identify critical packages vs leaf apps for sequencing
• Define non-goals (e.g., “no perfect types for untyped third-party JSON this quarter”)

Exit condition: Baseline error count + priority directories.

Stage 2: Compiler Flags Roadmap

Goal: Enable flags incrementally—fix clusters, not the whole repo at once.

Typical order (adapt)

1. strictNullChecks (often highest value)
2. noImplicitAny on new files + ratchet old
3. strictFunctionTypes, strictBindCallApply
4. noUncheckedIndexedAccess (verbose—plan for undefined unions)
5. exactOptionalPropertyTypes (sharp edges—later)

Techniques

• // @ts-expect-error with ticket over blind @ts-ignore
• Path-specific tsconfig extends for stricter packages
• CI gate: no new any in changed lines (eslint @typescript-eslint/no-explicit-any)

Exit condition: Flag timeline with owners per package.

Stage 3: Boundary Typing (IO Edges)

Goal: Validate external data once; internal code trusts narrowed types.

Patterns

• zod / io-ts / valibot for runtime parse at API boundary
• satisfies for config objects—keeps literal types
• Avoid casting from unknown without validation

APIs

• Generated types from OpenAPI/graphql-codegen when possible
• Branded types for IDs (type UserId = string & { __brand: 'UserId' }) to prevent mix-ups

Exit condition: New IO code has parse → typed pipeline documented.

Stage 4: Narrowing & Exhaustiveness

Goal: Control flow analysis works for you—discriminated unions, never checks.

Practices