Gradual Migration
In this page:
Core Concept
Gradual migration is the practice of moving a JavaScript codebase to TypeScript over weeks or months, file by file, rather than blocking all other work on one large rewrite — the two file types compile together the entire time.
Example: Core Concept
// utils.ts and legacy.js compile together throughout the migration.
console.log("Gradual migration moves files to TypeScript over time, not all at once");Basic Setup
A basic setup combines allowJs, initially checkJs: false, and a loose (non-strict) tsconfig.json, so the project keeps building throughout the transition instead of breaking the moment the first .ts file appears.
Example: Basic Setup
// tsconfig.json: { "allowJs": true, "checkJs": false, "strict": false }
console.log("A loose config keeps the project building during the transition");Typed Example
A typed example of the usual sequencing: convert files with the fewest internal dependencies first (utility/helper modules), since they require touching the least other code to get passing type checks.
Example: Typed Example
// Convert low-dependency utility files first:
function formatCurrency(amount: number): string {
return `$${amount.toFixed(2)}`;
}
console.log(formatCurrency(19.5));Project Usage
In a real project, teams often mandate that any *new* file must be written in TypeScript from day one, while existing .js files get converted opportunistically whenever they're touched for an unrelated change.
Example: Project Usage
// Policy: all NEW files must be .ts; existing .js files convert opportunistically.
console.log("New-file TypeScript mandate plus opportunistic old-file conversion");Best Practices
Track migrated-vs-remaining file counts visibly (a CI check or dashboard) so the migration doesn't quietly stall once the easy, low-dependency files are done and only the hard, tangled ones are left.
Example: Best Practices
// CI check: migratedFiles / totalFiles as a visible percentage.
console.log("Track migration progress so it doesn't quietly stall");Chapter Quiz — Complete all 6 topics to unlock
0/6 topics done
Complete these topics first: