Lesson

TypeScript Migration

10 min reading
Free Course

Migrating from JavaScript to TypeScript Incrementally

Rewriting an entire production JavaScript repository into TypeScript over one weekend usually stalls releases and creates giant merge conflicts. A safe, incremental migration introduces tsconfig.json alongside existing .js files and converts modules gradually from the bottom of the dependency tree upward.

Each converted file improves editor autocomplete and catches bugs immediately while the rest of the app keeps shipping normally.

Four-Phase Incremental Migration Plan

flowchart LR
    A["1. Add tsconfig (allowJs)"] --> B["2. Convert Leaf Utils"]
    B --> C["3. Type Shared Models & APIs"]
    C --> D["4. Enable strict: true"]
  1. Add tsconfig.json with "allowJs": true: Keep "strict": false temporarily so existing .js files compile cleanly alongside new .ts files.
  2. Convert leaf modules first: Start with pure utility functions, constants, and data models that have few imports—other files immediately benefit from their types.
  3. Rename .js to .ts (or .tsx) per PR: Fix implicit any parameters and add explicit interfaces as you touch files during regular feature work.
  4. Tighten flags one by one: Turn on noImplicitAny, then strictNullChecks, and finally "strict": true using tools like ts-migrate or per-file // @ts-expect-error markers if needed.

Sample Starter Migration Config

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "allowJs": true,
    "checkJs": false,
    "noEmit": true
  },
  "include": ["src"]
}

Common Mistakes to Avoid

  • Changing logic while renaming .js to .ts: Do file renames and type fixes in separate commits from behavioral refactors so git blame and code reviews stay clean.
  • Replacing every unknown error with any permanently: Use unknown or // TODO: type with // @ts-expect-error so temporary gaps remain searchable.
  • Migrating top-level routes/pages before shared utilities: Converting UI pages first forces you to type untyped helpers blindly; work bottom-up from utilities and types.

Frequently Asked Questions

How long should strict: false stay in tsconfig.json?

Use per-file strictness or enable strict: true as early as possible on new files (or run a separate tsconfig.strict.json for converted directories) so technical debt stops growing.

Should I use ts-migrate on large repositories?

Yes, on repositories with hundreds of files, ts-migrate automates renaming and inserts tracked // @ts-expect-error comments so CI stays green while teams clean modules up iteratively.

What happens to third-party packages during migration?

Check which packages lack built-in .d.ts files and run npm i -D @types/<package> for each untyped dependency.

Save Your Progress

Unlock Your
Full Potential.

Sign in to track your learning journey, earn industry-recognized certificates, and join our elite developer community.

Quick Access With

Enterprise-Grade Security Protocol

Try it Yourself

Experiment with the code from this lesson in our interactive playground.

Open Playground
TypeScript Topic Hub

Stuck on this lesson?

Join our community of senior developers.

Ask in Forum