TypeScript Migration
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"]
- Add
tsconfig.jsonwith"allowJs": true: Keep"strict": falsetemporarily so existing.jsfiles compile cleanly alongside new.tsfiles. - Convert leaf modules first: Start with pure utility functions, constants, and data models that have few imports—other files immediately benefit from their types.
- Rename
.jsto.ts(or.tsx) per PR: Fix implicitanyparameters and add explicit interfaces as you touch files during regular feature work. - Tighten flags one by one: Turn on
noImplicitAny, thenstrictNullChecks, and finally"strict": trueusing tools likets-migrateor per-file// @ts-expect-errormarkers 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
.jsto.ts: Do file renames and type fixes in separate commits from behavioral refactors sogit blameand code reviews stay clean. - Replacing every unknown error with
anypermanently: Useunknownor// TODO: typewith// @ts-expect-errorso 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.
Unlock Your
Full Potential.
Sign in to track your learning journey, earn industry-recognized certificates, and join our elite developer community.
Quick Access With
Try it Yourself
Experiment with the code from this lesson in our interactive playground.