How we gradually migrated to TypeScript at Unsplash

Oliver Joseph Ash
Mar 14, 2018 · 3 min read
Image for post
Image for post

When I joined Unsplash, I frequently watched as bugs inevitably slipped into the codebase due to human error. Having worked extensively with TypeScript in my prior work and side projects, I understood how static types could help.

As well as helping to prevent bugs, static types provide living documentation which helps to better understand and maintain legacy code. TypeScript also harnesses the static types to provide powerful and reliable refactoring tools, such as renaming symbols and object properties.

Our migration to TypeScript had to be gradual, so team members could learn the new syntax on the job, and so we could start to get a feel of the real benefits before fully committing. Thankfully, adding TypeScript does not have to be a large and daunting task — any JavaScript project, small or large, can easily begin a gradual migration to TypeScript.

One Make Day I decided to attempt the start of our gradual migration. This is how we did it.

Using TypeScript as a type checker for JS files

To add TypeScript to a project, add a . Use the , and options to define your dependency graph. (I prefer to use to specify the entry points, and let TypeScript trace the dependency graph from there.)

TypeScript allows you to enable type checking for JS files. We went with option of enabling the compiler option.

By default, TypeScript is very relaxed. TypeScript will infer types where possible. Everything else will be typed as by default.

It would have been a lot of work to add TypeScript to our compilation pipeline, so we decided to use TypeScript simply as a type checker instead. This is possible by running TypeScript with the compiler option: run to type check your app.

I spent about a day fixing all the errors, either by fixing the code or adding missing type annotations with JSDoc. Most of the errors were bugs we didn’t know about.

We then added type checking as a build step, and everyone in the team enabled TypeScript in their IDEs (or just switched to VSCode ;-)) so they could see the type errors whilst developing.

Gradually add JSDoc

TypeScript allows you to add type annotations without deviating from the JavaScript standard using JSDoc:

/** @type {number} */
const foo = 1

We gradually added JSDoc type annotations to our application. Again, this meant we could start to get a feel for TypeScript and using types in our application but without committing to any changes in our compilation pipeline.

Gradually add third party typings

All modules are implicitly typed as . We gradually added typings from DefinitelyTyped. As we did so, new type errors emerged, usually pointing to bugs we didn't know about.

Gradually migrating from JS to TypeScript syntax

After awhile of using JSDoc and TypeScript in this way, we wanted the true power of TypeScript syntax to define our types, instead of JSDoc. It took me 2 (hack) days to get TypeScript added to our compilation pipeline, on the server and client.

Adding TypeScript to a compilation pipeline will be made easier with Babel v7, which adds support for TypeScript syntax. Although you may find you don’t need any of Babel’s features after switching to TypeScript, as we did.

At this point, all our files were still . We were now free to gradually rename a file to (or ) and start using TypeScript syntax instead of JSDoc.

const foo: number = 1;

Today, over 60% of our codebase is TypeScript (/). Other team members are eagerly continuing the migration.

Gradually enabling stricter compiler options

Since we started, we’ve enabled some of the stricter compiler options, such as and . Enabling each of these took about 0.5-1 days in order to resolve all the new type errors.

Our next step would be to enable . At present, this would be an immense job, because so many things are still typed implicitly as . However, we are constantly adding types, so my hope is this will be possible sometime in the next year.

Unsplash Blog

Behind the scenes building the open photography movement at…

Medium is an open platform where 170 million readers come to find insightful and dynamic thinking. Here, expert and undiscovered voices alike dive into the heart of any topic and bring new ideas to the surface. Learn more

Follow the writers, publications, and topics that matter to you, and you’ll see them on your homepage and in your inbox. Explore

If you have a story to tell, knowledge to share, or a perspective to offer — welcome home. It’s easy and free to post your thinking on any topic. Write on Medium

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store