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#

• Discriminated unions for states: { status: 'loading' } | { status: 'ok', data: T }
• switch with assertNever(x) for compile-time exhaustiveness
• Optional chaining vs explicit undefined handling—be consistent in module

Nullability#

• Prefer undefined vs null one convention per codebase section

Exit condition: Representative modules refactored with fewer optional footguns.

---

Stage 5: Generics & Patterns#

Goal: Reuse without any soup— constraints and defaults.

Guidance#

• extends constraints; avoid unconstrained generics unless truly generic
• Conditional types sparingly— readability over cleverness in app code
• ReturnType / Parameters for inference glue
• Avoid mutable array inference surprises— explicit element types when needed

Performance#

• Huge mapped types can slow tsc— split types or simplify

Exit condition: Style guide section for generics in shared libraries.

---

Stage 6: Verify & Guardrails#

Goal: Strictness sticks— regressions caught in CI.

CI#

• tsc --noEmit required green for affected projects
• Type-aware ESLint rules; pre-commit optional
• dtslint or tsd for library typings tests when authoring packages

Refactor safety#

• Small PRs per module; runtime tests still required—types don’t replace tests

---

Final Review Checklist#

• Baseline metrics and roadmap for flags
• IO boundaries validated with schemas or codegen
• Discriminated unions / exhaustiveness for key state machines
• Generics style documented for shared code
• CI enforces typecheck on merge

Tips for Effective Guidance#

• Prefer unknown over any—forces narrowing at use site.
• When user fights noUncheckedIndexedAccess, show helper getters or Record patterns.
• Monorepo: align TypeScript version across packages— version skew causes phantom errors.

Handling Deviations#

• AllowJS mixed codebase: typed wrappers for critical paths first.
• Third-party untyped libs: local d.ts or wrapper module with narrow exports.