Frontend5 min read
Migrating a Legacy Codebase to TypeScript Strict Mode
Flipping strict mode on a five-year-old codebase in one commit is how migrations die. Here's the incremental path that actually finishes.
Tanjil Ahmed
Lead Software Engineer · Notionhive
Every team wants strict TypeScript. Almost none can afford to stop feature work for the weeks it takes to fix every resulting error in a large codebase. The migrations that actually finish are the ones that never ask for that pause.
Turn on strict per-directory, not globally
TypeScript's `strict` flag is all-or-nothing at the project level, but you can scope it with a layered `tsconfig` — a strict config for new and migrated directories, a looser one for the rest, composed through project references. New code is strict from day one; legacy code migrates on its own schedule.
- Start with `noImplicitAny` alone — it catches the most bugs for the least churn.
- Migrate directory by directory, starting with the most-imported shared modules.
- Ban new `any` in code review before the whole codebase is clean.
- Track the error count in CI as a number that must not go up — visible, ratcheting progress.
A strictness migration that requires a feature freeze is a migration that dies in someone's backlog.