ts-migrate

ts-migrate is a tool designed to accelerate the migration of JavaScript or partial TypeScript projects into compiling TypeScript projects.

Key characteristics:

• It produces code that passes the build, but requires manual follow-up to improve type safety.
• The output will contain many // @ts-expect-error comments and any types that should be refined over time.
• It uses a plugin-based architecture, allowing for customizable migration configurations.
• It is highly extensible; users can create custom configs by combining different sets of plugins.

To run migrations programmatically, import migrate and MigrateConfig from ts-migrate-server. You must provide a rootDir (the directory containing input files) and a config instance. The config instance can be used to add plugins. The migrate function returns an exit code as a number.

import path from 'path';
import { migrate, MigrateConfig } from 'ts-migrate-server';

// get input files folder
const inputDir = path.resolve(__dirname, 'input');

// create new migration config. You can add your plugins there
const config = new MigrateConfig();

// run migration
const exitCode = await migrate({ rootDir: inputDir, config });

process.exit(exitCode);

You can install ts-migrate as a development dependency using npm or yarn.

npm install --save-dev ts-migrate
# or
yarn add --dev ts-migrate

To migrate an entire project, use the ts-migrate-full command. This command performs a git add and git commit after each major step to allow for incremental progress. Note that full migrations can take a significant amount of time.

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

Install the ts-migrate-plugins package using npm or yarn to access the set of codemods used for transforming JS/JSX to TS/TSX.

npm install --save-dev ts-migrate-plugins

# or

yarn add --dev ts-migrate-plugins

Install ts-migrate-server as a development dependency using npm or yarn.

npm install --save-dev ts-migrate-server

# or

yarn add --dev ts-migrate-server

The ts-migrate-full.sh script automates the complete migration process for a frontend folder, converting it into a TypeScript project. It performs the following steps:

1. Initializes tsconfig.json: Creates a configuration file if one does not exist.
2. Renames files: Converts .js/.jsx files to .ts/.tsx.
3. Fixes TypeScript errors: Runs the migrate command to apply automated fixes.
4. Verifies compilation: Runs tsc --noEmit to check for remaining errors.

Pre-requisites:

• Ensure you have a clean git slate (no local changes).
• Work on a new git branch.
• Ensure npm install or yarn install has been run to provide the necessary dependencies.

Usage: Pass the path to the frontend folder as the first argument. Any subsequent arguments are passed directly to the underlying ts-migrate CLI commands (rename and migrate).

To run a migration, import a plugin from ts-migrate-plugins and use MigrateConfig from ts-migrate-server to compose your migration pipeline. Pass the configuration and the target directory to the migrate function.

import path from 'path';
import { tsIgnorePlugin } from 'ts-migrate-plugins';
import { migrate, MigrateConfig } from 'ts-migrate-server';

// get input files folder
const inputDir = path.resolve(__dirname, 'input');

// create new migration config and add ts-ignore plugin with empty options
const config = new MigrateConfig().addPlugin(tsIgnorePlugin, {});

// run migration
const exitCode = await migrate({ rootDir: inputDir, config });

process.exit(exitCode);

The example demonstrates how a configuration of multiple plugins can transform JavaScript into typed TypeScript.

Input (JavaScript):

function mult(first, second) {
    return first * second;
}

Output (TypeScript) after applying plugins:

function tlum(tsrif: number, dnoces: number): number {
  console.log(`args: ${arguments}`)
  return tsrif * dnoces;
}

function mult(first, second) {
    return first * second;
}

// ... after plugins ...

function tlum(tsrif: number, dnoces: number): number {
  console.log(`args: ${arguments}`)
  return tsrif * dnoces;
}