10 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.

10.1 Three strategies

These are three strategies for migrating to TypeScript:

• We can support a mix of JavaScript and TypeScript files for our code base. We start with only JavaScript files and then switch more and more files to TypeScript.

• We can keep our current (non-TypeScript) build process and our JavaScript-only code base. We add static type information via JSDoc comments and use TypeScript as a type checker (not as a compiler). Once everything is correctly typed, we switch to TypeScript for building.

• For large projects, there may be too many TypeScript errors during migration. Then snapshot tests can help us find fixed errors and new errors.

More information:

• “Migrating from JavaScript” in the TypeScript Handbook

10.2 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.

10.3 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:

• §4.4 “Using the TypeScript compiler for plain JavaScript files”

• “How we gradually migrated to TypeScript at Unsplash” by Oliver Joseph Ash

10.4 Strategy: migrating large projects by snapshot testing the TypeScript errors

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

10.5 Conclusion

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. Talk to your team w.r.t. prioritization:
  • Sometimes finishing the migration quickly may take priority.
  • Sometimes the code remaining fully functional during the migration may be more important.
  • And so on…