Running ts-migrate on a Project
What you'll learn: How to install, configure, and execute ts-migrate to automatically convert an existing JavaScript codebase to TypeScript with minimal manual intervention.
What Is ts-migrate Execution?
ts-migrate is an automated migration tool created by Airbnb. When you "run" ts-migrate, you're executing a multi-step transformation pipeline that renames .js files to .ts, adds type annotations where possible, and strategically uses type suppressions (like @ts-expect-error) to get your codebase compiling quickly. Think of it like an automated first draft—it won't be perfect, but it gets you 80% of the way there instantly.
Installation
First, install ts-migrate in your project:
npm install --save-dev ts-migrate
Or globally:
npm install -g ts-migrate
The local installation is generally preferred for team consistency.
Basic Execution
Run ts-migrate on your source directory:
npx ts-migrate migrate ./src
This single command orchestrates multiple internal "plugins" that progressively transform your code.
What Happens During Execution
When you run ts-migrate, it executes several transformation passes:
- Renames files from
.jsto.ts(or.jsxto.tsx) - Adds type suppressions where errors would occur
- Inserts any casts where types can be inferred but are problematic
- Creates placeholder types for functions and variables
- Hoists declarations to resolve ordering issues
- Generates a tsconfig.json if one doesn't exist
All of this happens in one command, but you can configure which plugins run.
Configuration Options
You can customize the migration with flags:
npx ts-migrate migrate ./src --aliases-to-ignore react,lodash
Common options include ignoring specific imports, controlling strictness, or targeting specific subdirectories.
Validating the Output
After running ts-migrate, compile your project:
npx tsc --noEmit
The goal is zero errors immediately after migration—ts-migrate achieves this through liberal use of suppressions. Your job then becomes gradually removing those suppressions and adding proper types.
Post-Migration Cleanup
The generated code will contain many @ts-expect-error comments and any types. This is intentional. You now have a compiling TypeScript project that you can incrementally improve by replacing suppressions with real types, file by file.
Key Takeaway: ts-migrate automates the tedious file-renaming and initial setup of a TypeScript migration, using type suppressions to ensure immediate compilation success while giving you a foundation for gradual type improvement.