Migrating Large JavaScript Projects to TypeScript with Airbnb's ts‑migrate

More and more projects are migrating JavaScript code to TypeScript (TS) because TS adds static types that improve readability, maintainability, and robustness.

Two migration approaches exist for large codebases:

Mixed migration : migrate files one by one, fixing type errors as they appear. The allowJS compiler option lets JavaScript and TypeScript coexist, allowing continuous development without a full stop, though the process can be lengthy.

Full migration : convert the entire project at once, initially adding any types and @ts-ignore comments to keep the project compiling, then gradually replace them with precise types. This approach ensures consistency across the project.

Airbnb open‑sourced ts-migrate , a tool that automates the conversion from JavaScript (or partially typed TypeScript) to a fully compiled TypeScript project.

Overview

ts-migrate consists of three packages: ts-migrate , ts-migrate-server , and ts-migrate-plugins . The server runs two components: a TSServer instance that communicates with editors (e.g., VSCode) and a migration runner that coordinates the migration steps.

The migration runner performs the following actions:

Parses tsconfig.json .

Creates .ts files.

Sends each file to the TypeScript language server for diagnostics ( semanticDiagnostics , syntacticDiagnostics , suggestionDiagnostics ) and uses the results to locate problems.

Runs all configured plugins on each file, updating the source when a plugin makes changes and notifying the language server.

Common Plugins

Plugins live in the ts-migrate-plugins directory and are built on jscodeshift . Two core plugins are:

explicitAnyPlugin : adds any to variables that cause semantic type errors, allowing the code to compile.

declareMissingClassPropertiesPlugin : adds missing class property declarations with any types.

Basic Usage

Install and configure TypeScript

Install TS: npm install --save-dev typescript

Initialize a tsconfig.json : npx tsc --init

If using React, install its type definitions: npm install --save-dev @types/react

Convert JS files to TS

Install ts‑migrate: npm install --save-dev ts-migrate

Rename .js/.jsx files to .ts/.tsx: npm run ts-migrate -- rename <project-dir> --sources <specific-dir>

Migrate the renamed files: npm run ts-migrate -- migrate <project-dir> --sources <specific-dir>/file.tsx

It is recommended to commit the rename changes before committing the migration changes so that Git treats each file as a modification rather than a delete‑add pair.

Example

Given src/examples/example.js containing various type errors, the following commands rename and migrate it:

npm run ts-migrate -- rename ./ --sources ./src/examples

After renaming, the file becomes src/examples/example.ts . Then run:

npm run ts-migrate -- migrate ./ --sources ./src/examples/example.ts

ts‑migrate will add any types, @ts-ignore comments, and other scaffolding. Developers must later replace any with specific types and remove the ignore comments.

Command‑line Options

-h, --help : display help.

-i, --init <folder> : create a tsconfig.json in the specified folder.

-m, --migrate <folder> : run codemods to fix TypeScript errors.

-rn, --rename <folder> : rename JavaScript/JSX files to TypeScript/TSX.

-ri, --reignore <folder> : re‑run ts‑ignore on the project.

All commands accept the --sources (or -s ) flag to limit the operation to specific paths, effectively overriding the include field of tsconfig.json .

While ts‑migrate automates much of the conversion, it cannot fully resolve all type errors; developers must manually replace any with concrete types and address any remaining issues.

ts‑migrate: https://github.com/airbnb/ts-migrate