Course contentsShow
← TypeScript
Lesson 1004 of 1,79623. Type AssertionsFree lesson

Progressive Migration Scenarios

Using assertions temporarily during JavaScript to TypeScript migration to unblock progress on typed code.

Progressive Migration Scenarios

What you'll learn: How to use type assertions strategically to unblock progress when migrating JavaScript codebases to TypeScript, without compromising your entire migration effort.

The Migration Challenge

When converting a large JavaScript codebase to TypeScript, you'll inevitably hit moments where fully typing something would require refactoring dozens of interconnected files. You're stuck: you can't move forward without types, but you can't add types without massive changes.

This is where progressive migration comes in—using temporary type assertions as "scaffolding" to keep moving forward.

The Strategic Use of Assertions

Think of assertions during migration like construction scaffolding: they're temporary structures that let you work safely at height. You wouldn't leave scaffolding up forever, but it's essential while the real building takes shape.

During migration, you can use as assertions or non-null assertions (!) to tell TypeScript "trust me on this for now" while you continue converting other files. The key word is temporary.

When This Makes Sense

Use assertions as migration scaffolding when:

  • The correct type exists but requires major refactoring to prove it (e.g., a function you know returns User but TypeScript sees unknown)
  • You're working through files incrementally and need one file typed to proceed to the next
  • Third-party code integration is blocking your migration path
  • You can document the assertion with a TODO comment for future cleanup

The Migration Pattern

Mark your temporary assertions clearly so they don't become permanent:

// TODO(migration): Remove assertion once UserService is typed
const user = fetchUser() as User;

Track these TODOs as technical debt, then systematically eliminate them as surrounding code gains proper types.

Key Takeaway: Type assertions are legitimate tools during JavaScript-to-TypeScript migration when used temporarily and intentionally—they let you make incremental progress without getting stuck, as long as you commit to removing them once the surrounding code is properly typed.