TypeScript Migration Momentum
Teams adopt TypeScript to catch bugs at compile time and improve code maintainability. The migration starts with a few files, strict mode off, liberal use of 'any'. Initial results are promising — IDE autocomplete improves, some bugs are caught early. But the migration creates a two-speed codebase. Typed and untyped code coexist, creating a boundary tax at every interface. The 'any' escape hatch becomes structural — teams use it to avoid blocking work, then never come back to fix it. Strict mode gets delayed indefinitely because enabling it would surface thousands of errors. Meanwhile, the type system's complexity grows: generics, conditional types, mapped types, template literal types. Senior engineers spend increasing time on type gymnastics rather than business logic. The migration that was supposed to take 3 months is still ongoing 2 years later.
What people believe
“TypeScript catches bugs at compile time and improves code quality.”
| Metric | Before | After | Delta |
|---|---|---|---|
| Migration timeline | 3 months estimated | 2+ years actual | +700% |
| Senior engineer time on types | 0% | 15-25% | +20% |
| Build time | Baseline | 2-3x slower | +150% |
| Compile-time bugs caught | 0 | 10-15% of total bugs | +12% |
Don't If
- •Your team lacks TypeScript expertise and you can't afford the learning curve
- •Your codebase is small enough that runtime testing catches most bugs
If You Must
- 1.Start with strict mode on from day one — never plan to 'enable it later'
- 2.Ban 'any' in new code via ESLint rules, not just guidelines
- 3.Set a hard deadline for migration completion and cut scope if needed
- 4.Use runtime validation at API boundaries regardless of TypeScript types
Alternatives
- JSDoc type annotations — Type checking without migration — works with TypeScript compiler
- Greenfield TypeScript — New services in TypeScript, leave existing JS alone
- Runtime validation libraries — Zod, io-ts — validate at boundaries where bugs actually occur
This analysis is wrong if:
- Teams completing TypeScript migrations report net positive ROI within the first year including migration costs
- TypeScript strict mode adoption rate exceeds 70% among teams that started migration
- Bug density reduction from TypeScript exceeds the engineering time invested in type maintenance
- 1.State of JS Survey 2024: TypeScript Adoption
89% of JS developers use TypeScript, but satisfaction with migration experience is declining
- 2.Airbnb TypeScript Migration Postmortem
Multi-year migration effort that required dedicated team and tooling investment
- 3.DHH: Turbo 8 Drops TypeScript
High-profile decision to remove TypeScript from Turbo framework, citing complexity overhead
- 4.Bloomberg Engineering: TypeScript at Scale
Build time and type complexity challenges at large codebase scale
This is a mirror — it shows what's already true.
Want to surface the hidden consequences of your engineering decisions?