Migration Strategy
In this page:
Core Concept
Migrating a JavaScript codebase to TypeScript works best incrementally, file by file, rather than attempting one big rewrite — TypeScript is a superset of JavaScript, so a .js file becomes valid TypeScript source the moment it's renamed .ts.
Example: Core Concept
// utils.js -> utils.ts is valid the moment you rename it.
console.log("TypeScript is a JS superset -- migrate incrementally, file by file");Basic Setup
A basic setup enables "allowJs": true and "checkJs": false in tsconfig.json first, letting .js and .ts files coexist and compile together before any type errors are enforced.
Example: Basic Setup
// tsconfig.json: { "compilerOptions": { "allowJs": true, "checkJs": false } }
console.log("allowJs lets .js and .ts coexist before enforcing any type errors");Typed Example
A typed example of the usual path: rename one low-dependency utility file to .ts, fix the handful of type errors TypeScript immediately flags, then move to files that import it, working outward from the leaves of the dependency graph.
Example: Typed Example
// Step 1: rename a low-dependency utils.js to utils.ts, fix its errors.
// Step 2: move outward to files that import it.
function double(x: number): number { return x * 2; }
console.log(double(5));Project Usage
In a real project, teams often gate the migration with "strict": false initially, then flip individual strict-mode flags (noImplicitAny, strictNullChecks, etc.) on one at a time as the codebase's type coverage improves.
Example: Project Usage
// tsconfig.json starts with { "strict": false }, flags enabled one at a time.
console.log("Teams flip noImplicitAny, strictNullChecks, etc. incrementally");Best Practices
Track migration progress with a metric like "percentage of files that are .ts" or a strictness-adoption dashboard, since an all-or-nothing migration attempt on a large codebase rarely finishes.
Example: Best Practices
// Track "% of files that are .ts" as a migration progress metric.
console.log("An all-or-nothing migration attempt on a large codebase rarely finishes");Chapter Quiz — Complete all 6 topics to unlock
0/6 topics done
Complete these topics first: