TypeScript Migration

TypeScript Migration: Converting JavaScript Codebases Strategy

Migrating a large JavaScript project to TypeScript should be done incrementally using a structured step-by-step strategy to avoid disrupting ongoing development.

Incremental Migration Pipeline

flowchart TD
    A["Phase 1: Setup tsconfig.json with allowJs: true"] --> B["Phase 2: Add // @ts-check to Critical JS Files"]
    B --> C["Phase 3: Rename .js Files to .ts / .tsx"]
    C --> D["Phase 4: Annotate Functions & Extract Interfaces"]
    D --> E["Phase 5: Enable strict: true in tsconfig.json"]

Key tsconfig.json Flags for Migration

{
  "compilerOptions": {
    "allowJs": true,
    "checkJs": false,
    "noImplicitAny": false,
    "strictNullChecks": false,
    "outDir": "./dist"
  }
}

Migration Code Progression Example

Before (Plain JavaScript mathUtils.js):

function calculateDiscount(price, percent) {
  return price - (price * (percent / 100));
}

After Migration (TypeScript mathUtils.ts):

export interface DiscountRequest {
  price: number;
  percent: number;
}

export function calculateDiscount(request: DiscountRequest): number {
  if (request.price < 0 || request.percent < 0) {
    throw new Error("Invalid price or discount percentage");
  }
  return request.price - (request.price * (request.percent / 100));
}

Best Practices & Gotchas

• Don't Attempt a Full Rewrite Overnight: Migrate one module or utility folder at a time.
• Start with Lowest-Level Utilities: Migrate leaf utility functions first, followed by data models, service layers, and finally UI components or entry controllers.
• Use any Temporarily During Initial File Renaming: It is acceptable to use any temporarily when renaming .js to .ts to get a passing build, then refine types in follow-up iterations.

Self-Check Challenge

Which tsconfig.json flag allows TypeScript to compile and include JavaScript (.js) files in the project build? (Answer: "allowJs": true)