How to Incrementally Migrate 100k Lines of Code to Typescript

computer science…Using a Snapshot Test

Even with the loosest settings, migrating a large project to TypeScript may turn out to be insurmountable. The number of errors quickly becomes overwhelming.

You may think the best options for fixing this situation is to use a mix of TypeScript and JS (using the allowJs flag), however, there is a risk of a large amount of code never being typed because there is not enough incentive and feedback to do so.

If you run TypeScript on a large project after renaming files you may be faced with something similar to this:

Typescript migration

Possibly, there could be many more errors: this project started with 15k errors!

Unfortunately for a project of any sufficient size, you’re going to run into trouble trying to migrate to TypeScript in one go.

So what are your options?

Conversion technique: Individual Effort Team Effort Incremental Convert Changed Files Team effort -Checklist Incremental Snapshot Test
Quick
High Quality Results
Low Team-Coordination
Non-Breaking For Wip
Scalable
Can Enable Strict Rules On Day 1
Easy To Add Stricter Rules
Will Achieve 0 Errors
Easily Repeatable For New Rules

Think about it.

Ideally your goal is to achieve 0 errors and obtain an easily repeatable process for preventing new errors. In order to do so, your best option might be the creation of a snapshot test.

On a high-level, using a snapshot test requires creating a test that runs TypeScript and saves a snapshot of all the errors along with filenames and line numbers. This test will fail anytime lines are shifted on a file with errors, or when new errors are added to the codebase — this serves as a reminder to fix type errors when adding or modifying code. As this method is mostly automated, it requires a low coordination level.

Using this process also greatly facilitates incremental increases of the strictness of type checking, since the incremental approach is the same.

In essence, the snapshot test is closer to the code than any checklist process and requires low team-coordination.

How to create a snapshot test of TypeScript errors?

This repo (ActiveViam/typescript-migration-demo) shows a basic example of how to snapshot test TypeScript errors.

Here’s how it works, consider the following 3 untyped JS files:

// add.js
export default function add(a, b) {
  a + b
}
// subtract.js
export default function subtract(a, b) {
  a - b
}
// example.js
import add from './add'
import subtract from './subtract'

add('1', 3, 'hello world')

subtract('1', 3, 'hello world')

When we convert this sample to TypeScript, after changing its extensions and adding a tsconfig.json file, it will produce a number of type errors:

Typescript tutorial

At this point you should run the snapshot test and commit the result. The snapshot of the errors will look something like this:

What happens when I fix or add type errors?

When you fix type errors you can run yarn check-ts -u to update the snapshot, and you will commit something like this:

typescript react

If you were to add a type error by accident you would see something like this:

typescript interface

So at this point if you are doing PR reviews your reviewer would probably reject this change.

Using ESLint (or other tools)

This technique applies to any pattern that can be detected using code quality tools. For example it’s possible to write ESLint rules for bad practices specific to your codebase. You can then incrementally remove them using this technique.

Conclusion

Among all the possible techniques to migrate to TypeScript this one  definitely provides the greatests benefits.

 

Like this blog?
Follow us on LinkedIn
to stay up-to-date with the latest blog posts!

This entry was posted in Miscellaneous and tagged , , , . Bookmark the permalink.

Comments are closed.