How To Port A JavaScript Project To TypeScript

As you might know, TypeScript has picked up huge momentum over the last couple of years, and tons of projects are porting their JavaScript code to TypeScript:

In this post, I'll show you how to port existing JavaScript projects to TypeScript.

If you don't know TypeScript yet, now is the time to learn it.

Below I'll cover:

  • benefits of porting your JavaScript to TypeScript

  • setting up TypeScript in your JavaScript project

  • converting individual modules

  • importing types for dependencies and NPM packages

  • other best practices and problem solving

  • TypeScript boilerplates you can use

But if you want to learn TypeScript really well, we've got you covered: The Beginner's Guide to TypeScript is available exclusively to newline Pro members. You can join here.


Why Port Your JavaScript Code To TypeScript#

TypeScript promises to make JavaScript code more type-safe. This means that functions and variables in your code will not produce errors or bugs due to passing or assigning the wrong type arguments.

This is a big deal because type errors are a significant, and frequent, source of bugs in just any codebase.

The problem is that JavaScript is dynamically typed, which gives you less support for eliminating type errors. Avoiding type errors in JavaScript requires diligence and rigorous testing.

TypeScript helps solve the problem!

While testing doesn't go away, it's a massive help to have your editor inform you of any mismatched types as you code.

Setting Up TypeScript In Your Existing JavaScript Project#

There are a lot of TypeScript boilerplates depending on the type of project you're starting. But what if you already have an existing project and you want to add TypeScript to it?

The first step in setting up TypeScript for your project is to create a folder structure with src and dest directories. Here, src is where you will write your TypeScript files. Likewise, dest is where your JavaScript files will be generated once TypeScript compiles your files in the src directory.

Note, you can name these two directories anything you want, e.g. built for the dest directory.

Next, create a TypeScript configuration file, named tsconfig.json in the root folder in your project.

It controls how TypeScript compiles your source files. Here is a basic tsconfig.json file.

As you can see, the include section specifies where your source files reside. The outDir specifies where to place compiled files. The target is the JavaScript version you want to target.

Now you can compile TypeScript files into JavaScript by running the command tsc in the top level directory in your project.

Convert .js JavaScript Files Into .ts TypeScript Files#

You're now able to write new .ts and .tsx files in your previously JavaScript-only project, but how do you change existing JavaScript files to TypeScript?

The good part about TypeScript is that you don't have to! You can keep existing JavaScript files in your source files and only convert them gradually to TypeScript.

To convert a JavaScript file into TypeScript, change the file extension from .js or .jsx to the TypeScript equivalent: .ts or .tsx.

You might see some errors when TypeScript compiles, because there might be missing types in your new ts files. However, by default, TypeScript will still compile and output the .js files in spite of any errors.

To fix errors, add the types where they are missing, e.g :

  • in functions

  • in variables

  • in arguments to functions

  • etc.

Adding Types To Functions#

To convert JavaScript functions into TypeScript functions, you must add types to the arguments as well as specify the return type.

TypeScript type inference also infers types where possible, meaning that you don't have to explicitly specify all the types in your functions in order to get the file to compile without errors. You'll have to decide the explicitness level you want in your code.

Here's a sample JavaScript function we want to convert into TypeScript:

Here is how it looks in TypeScript when we add full type annotations to the function.

TypeScript is able to infer the return type automatically, so you'll often see the above function typed more simply as follows, using type inference to supply the missing type information:

On compilation, this produces exactly the same JavaScript ouput in both cases.

Installing Types For Dependencies#

Many third-party libraries and NPM packages now supply TypeScript type definitions. These make it possible to use TypeScript type checking and editor autocomplete when you use these libraries.

To get these benefits, you must install the type definitions for the package you want to use.

Suppose you want to use the react package. You can install its type definitions from NPM by running the command:

npm install --save @types/react

If you need types for a particular package, check NPM for the type definitions.

Best Practices And Troubleshooting#

You might run into problems as you go about porting your JavaScript project to TypeScript.

If you want to learn more about working with TypeScript and building apps - for both the browser and Node.js - we have a brand new book for learning TypeScript called The Beginner's Guide to TypeScript and it's available exclusively to newline Pro members.

It's written by Christian Santos, a Facebook engineer, who has used TypeScript extensively in his work.

TypeScript Boilerplates#

If you use Angular or React, both of these frameworks have TypeScript support built in.

  • create-react-app supports a typescript flag, which generates your project using TypeScript

  • Angular is TypeScript by default

If you're creating a Node.js project, Microsoft ships a Node.js Starter.

If you're creating a library, a package I've used a bunch of times is tsdx which gives you a great zero-config starter for TypeScript package development.