Migration Strategy: any to unknown
What you'll learn: How to gradually and safely replace any with unknown in an existing codebase without breaking everything at once.
The Migration Challenge
You've inherited a codebase peppered with any, or you wrote it yourself when prototyping fast. Now you want the safety of unknown, but changing everything at once would cause a cascade of type errors across hundreds of files. The solution? Incremental migration.
Start at the Edges
Begin with functions that receive external data—API responses, JSON parsing, user input. These are high-value targets because they're where runtime errors actually happen:
// Before
function parseUserData(json: string): any {
return JSON.parse(json);
}
// After
function parseUserData(json: string): unknown {
return JSON.parse(json);
}
Now callers must validate before use. This surfaces dormant bugs immediately.
Work Inward, Not Outward
Don't start with low-level utilities used everywhere. Instead, migrate leaf nodes—code that few other modules depend on. This minimizes cascading changes:
- Leaf functions first (utilities, helpers)
- Internal module boundaries (private functions)
- Public APIs last (what other teams consume)
Use Compiler Flags as Guardrails
Enable noImplicitAny to prevent new any types from sneaking in while you clean up old ones. This creates a ratchet effect—the problem can't grow.
Hybrid Coexistence
It's okay to have both any and unknown during migration. Use comments to mark technical debt:
// TODO: migrate to unknown after dependent code is updated
function legacyHandler(data: any) { /*...*/ }
Key Takeaway: Migrate from the outside in—start where data enters your system, enable noImplicitAny to prevent backsliding, and work incrementally to avoid paralyzing your codebase with type errors.