Course contentsShow
← TypeScript
Lesson 1644 of 1,79637. Migrating JavaScript to TypeScriptFree lesson

Running ts-migrate on a Project

Step-by-step guide to installing ts-migrate, configuring it, and executing it on an existing JavaScript codebase.

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:

  1. Renames files from .js to .ts (or .jsx to .tsx)
  2. Adds type suppressions where errors would occur
  3. Inserts any casts where types can be inferred but are problematic
  4. Creates placeholder types for functions and variables
  5. Hoists declarations to resolve ordering issues
  6. 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.