Strategies for migrating to TypeScript

12 Strategies for migrating to TypeScript

This chapter gives an overview of strategies for migrating code bases from JavaScript to TypeScript. It also mentions material for further reading.

12.1 Strategy: mixed JavaScript/TypeScript code bases

The TypeScript compiler supports a mix of JavaScript and TypeScript files if we use the compiler option --allowJs:

TypeScript files are compiled.
JavaScript files are simply copied over to the output directory (after a few simple type checks).

At first, there are only JavaScript files. Then, one by one, we switch files to TypeScript. While we do so, our code base keeps being compiled.

This is what tsconfig.json looks like:

{
  "compilerOptions": {
    ···
    "allowJs": true
  }
}

More information:

“Incrementally Migrating JavaScript to TypeScript” by Clay Allsopp.

12.2 Strategy: adding type information to plain JavaScript files

This approach works as follows:

We continue to use our current build infrastructure.
We run the TypeScript compiler, but only as a type checker (compiler option --noEmit). In addition to the compiler option --allowJs (for allowing and copying JavaScript files), we also have to use the compiler option --checkJs (for type-checking JavaScript files).
We add type information via JSDoc comments (see example below) and declaration files.
Once TypeScript’s type checker doesn’t complain anymore, we use the compiler to build the code base. Switching from .js files to .ts files is not urgent now because the whole code base is already fully statically typed. We can even produce type files (filename extension .d.ts) now.

This is how we specify static types for plain JavaScript via JSDoc comments:

/**
 * @param {number} x - The first operand
 * @param {number} y - The second operand
 * @returns {number} The sum of both operands
 */
function add(x, y) {
  return x + y;
}

/** @typedef {{ prop1: string, prop2: string, prop3?: number }} SpecialType */
/** @typedef {(data: string, index?: number) => boolean} Predicate */

More information:

12.3 Strategy: linting before activating a compiler option

Projects that migrate to TypeScript often start with the default type checking and then add more checks, in stages – e.g.:

Initially: default checks
Activate strictNullChecks (prevents undefined and null from being used unless the type is T | undefined or T | null, respectively)
Activate noImplicitAny (prevents omitting types for parameters and more)
Activate strict (includes the previous two compiler options – which can be removed – and adds additional ones)

In contrast to compiler options, we can activate linting options on a per-file basis. This helps when switching from less strict type checking to stricter type checking: We can lint before making the switch. These are examples of useful rules that the TypeScript linter typescript-eslint provides:

Preparing for noImplicitAny:
Preparing for erasableSyntaxOnly:
- eslint-plugin-erasable-syntax-only

12.4 Strategy: Too many errors? Use snapshot testing

In large JavaScript projects, switching to TypeScript may produce too many errors – no matter which approach we choose. Then snapshot-testing the TypeScript errors may be an option:

We run the TypeScript compiler on the whole code base for the first time.
The errors produced by the compiler become our initial snapshot.
As we work on the code base, we compare new error output with the previous snapshot:
- Sometimes existing errors disappear. Then we can create a new snapshot.
- Sometimes new errors appear. Then we either have to fix these errors or create a new snapshot.

More information:

“How to Incrementally Migrate 100k Lines of Code to Typescript” by Dylan Vann

12.5 Tools that help with migrating to TypeScript

ts-migrate helps with the first step of moving from JavaScript to TypeScript: “The resulting code will pass the build, but a followup is required to improve type safety. There will be lots of //@ts-expect-error, and any that will need to be fixed over time. In general, it is a lot nicer than starting from scratch.”
type-coverage shows which percentage of identifiers have the type any.

12.6 Conclusion and further reading

We have taken a quick look at strategies for migrating to TypeScript. Two more tips:

Start your migration with experiments: Play with your code base and try out various strategies before committing to one of them.
Then lay out a clear plan for going forward. Discuss prioritization with your team:
- Sometimes finishing the migration quickly may take priority.
- Sometimes the code remaining fully functional during the migration may be more important.
- And so on…

Further reading:

“Migrating from JavaScript” in the TypeScript Handbook