ts-migrate - Stop manually converting JavaScript to TypeScript like a caveman

What is ts-migrate and Why It Exists

ts-migrate is Airbnb's migration tool that exists because manually converting large Java

Script codebases to TypeScript is a nightmare that makes you question your life choices.

Instead of spending months manually rewriting every file, ts-migrate brute-forces your JavaScript into compiling TypeScript.

Core Purpose and Reality Check

Airbnb built this because they had massive JavaScript codebases and converting them by hand would take until the heat death of the universe. The tool follows the "make it compile first, fix the types later" philosophy

• because perfect is the enemy of done, and perfect TypeScript migration is a myth.

At Airbnb, they used this on massive projects and got them compiling quickly.

Does it create beautiful, type-safe TypeScript? Hell no. Does it create TypeScript that actually compiles so you can start getting some benefits while you clean up the mess? Absolutely. [Large codebases](https://github.com/microsoft/Type

Script/wiki/Performance) benefit from gradual migration approaches, and TypeScript adoption statistics show the language's growing popularity in enterprise environments.

How This Thing Actually Works

Plugin-Based Architecture: ts-migrate uses a modular plugin system that you can customize.

The default setup assumes you're using React, which is great if you are and annoying if you're not. The plugins handle PropTypes conversion and other React-specific patterns pretty well.

Codemod Foundation:

Under the hood, it's using codemods (code modification scripts) to systematically transform your JavaScript.

It extracts type information from PropTypes (if you have them), handles [imports/exports](https://developer.mozilla.org/en-US/Web/Java

Script/Reference/Statements/import), and adds type annotations wherever it can figure them out.

The approach is similar to other AST transformation tools like jscodeshift.

"Smart" Type Inference:

The tool tries to infer types from your existing code patterns and Prop

Types definitions. When it can't figure something out (which is often), it falls back to any types aliased as $TSFixMe. This is by design

• it's better to have compiling code with any types than broken code.

Current Status and Compatibility

The latest version is 0.1.35, published 3 years ago in November 2022.

The package gets decent usage but isn't actively maintained anymore

• last real update was years ago. Works fine with React 17/18, untested with React 19 beta.

The tool generates TypeScript that compiles immediately but creates a mess you'll spend weeks cleaning up. This trade-off

• speed vs. quality
• makes it perfect for teams that need to get TypeScript benefits now while accepting they'll be fixing types for months afterward.

Similar migration strategies are discussed in the TypeScript handbook and migration guides.

ts-migrate gets you compiling Type

Script in 2 hours, but you'll spend 6 months explaining to your team why everything is typed as any.

Installation - The Easy Part

Install it like any other npm package. If you can't figure this out, TypeScript migration is the least of your problems:

Using npm:

npm install --save-dev ts-migrate

Using yarn:

yarn add --dev ts-migrate

Direct execution (if you're feeling brave):

npx ts-migrate <folder>

The Nuclear Option - Full Migration

⚠️ Fair warning: This will touch every JavaScript file in your project. Run this on a clean branch or you'll hate yourself:

npx -p ts-migrate -c \"ts-migrate-full <folder>\"

This command will bulldoze through your project and:

1. Initialize a tsconfig.json file
2. Rename .js/.jsx files to .ts/.tsx (yes, all of them)
3. Apply codemods to make TypeScript stop screaming
4. Commit changes at each step (so you can rollback when it breaks)

Pro tip: The automatic commits are actually useful because you'll definitely want to rollback some of this mess.

Platform Gotchas That Will Ruin Your Day

Windows users: The file renaming step occasionally fails with permission errors when files are open in your IDE. Close everything and pray.

M1 Macs: Sometimes have issues with the dependency tree during migration - if npm fails mysteriously, try using Node 16 with rosetta.

Docker builds: Need updating to handle .ts/.tsx files if they weren't already. Your build times will increase 2-3x initially because TypeScript is slower than Babel.

Webpack configuration: ts-migrate assumes standard module resolution. Custom webpack aliases will break everything. Prepare to update your Jest config too - ts-migrate changes file extensions but doesn't fix test setup.

Individual Command Usage

For more granular control, ts-migrate provides four distinct commands that can be run independently:

Initialize TypeScript configuration:

npx ts-migrate -- init <folder>

Rename JavaScript files to TypeScript:

npx ts-migrate -- rename <folder>

Apply migration codemods:

npx ts-migrate -- migrate <folder>

Re-run ignore comments for new errors:

npx ts-migrate -- reignore <folder>

Partial Migrations with --sources Flag

For large projects, you can migrate specific directories or files using the --sources flag, which accepts glob patterns:

## Migrate specific components
npx ts-migrate-full /path/to/project --sources \"src/components/**/*\"

## Include ambient types for better results  
npx ts-migrate-full /path/to/project \
  --sources \"src/components/**/*\" \
  --sources \"node_modules/**/*.d.ts\"

This approach is particularly useful for teams that want to migrate incrementally or test the tool on smaller sections before full project conversion.

What to Expect After the Tool Destroys Your Pristine JavaScript

After running ts-migrate, your project will compile, but it'll look like a TypeScript horror movie. Expect hundreds of @ts-expect-error comments and any types everywhere (aliased as $TSFixMe). This is normal. You're not doing anything wrong - the tool just creates compiling garbage that you'll spend months fixing.

Common failures include: ts-migrate chokes on barrel exports (index.js files with re-exports), dies on dynamic requires, and completely ignores HOCs. If you use Redux with connect(), prepare for a world of pain. When it encounters dynamic imports or weird webpack setups, it basically gives up and dumps any types everywhere. Don't even think about using it with Vue or Angular - it's React-only in practice, despite what the docs claim.

The reality of post-migration cleanup:

1. Day 1: Pop champagne, it compiles! Ship it to production immediately.
2. Week 2: First production bug because any types hid a real issue. Enable stricter linting.
3. Month 3: Junior dev asks why everything is $TSFixMe. Start writing documentation.
4. Month 6: Still finding any types in weird places. Consider this the new normal.
5. Year 2: Finally remove the last @ts-expect-error. Tool paid for itself months ago.

This approach lets you start getting TypeScript benefits (better IDE support, some type checking) immediately while accepting that you'll be cleaning up the mess until the next framework migration. The TypeScript compiler options can be gradually tightened as you improve your types, and ESLint TypeScript rules help maintain code quality during the transition.

Reality check: most teams never finish the cleanup. They just live with the $TSFixMe types forever and call it "TypeScript". At least it's better than the alternative: staring at a JavaScript codebase that crashes in production because someone passed a string where a number was expected. Again.