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.

But if you want to learn TypeScript really well, we've got you covered: 

 is available exclusively to newline Pro members. You can 

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.

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 

 is where you will write your TypeScript files. Likewise, 

 is where your JavaScript files will be generated once TypeScript compiles your files in the 

Note, you can name these two directories anything you want, e.g. 

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

 section specifies where your source files reside. The 

 specifies where to place compiled files. The 

 is the JavaScript version you want to target.

Now you can compile TypeScript files into JavaScript by running the command 

 in the top level directory in your project.

Convert .js JavaScript Files Into .ts TypeScript Files

 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 

 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 

You might see some errors when TypeScript compiles, because there might be missing types in your new 

 files. However, by default, TypeScript will still compile and output the 

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

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:

let add = function (x, y) {
    return x + y;
};

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

let add: (
  a: number,
  b: number
) => number = function (x: number, y: number) {
  return x + y;
};

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:

let add = function (
  x: number,
  y: number
): number {
  return x + y;
};

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

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.

 package. You can install its type definitions from NPM by running the command:

If you need types for a particular package, check 

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 

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

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

If you're creating a library, a package I've used a bunch of times is 

 which gives you a great zero-config starter for TypeScript package development.

<h1 data-node-type="titlePlaceholder" class="titlePlaceholder">How To Port A JavaScript Project To TypeScript</h1><p>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:</p><figure class="photo figure-position-inline"><img src="https://s3.amazonaws.com/assets.fullstack.io/n/20201208035620585_trends.png" attachmentid="958570c7-7959-4cff-9825-fbf61c03a6e1" contenteditable="false" data-width="1178" data-height="521"><div></div></figure><p>In this post, I'll show you how to port existing JavaScript projects to TypeScript.</p><p>If you don't know TypeScript yet, now is the time to learn it.</p><p>Below I'll cover:</p><ul><li><p>benefits of porting your JavaScript to TypeScript</p></li><li><p>setting up TypeScript in your JavaScript project</p></li><li><p>converting individual modules </p></li><li><p>importing types for dependencies and NPM packages </p></li><li><p>other best practices and problem solving</p></li><li><p>TypeScript boilerplates you can use</p></li></ul><p>But if you want to learn TypeScript really well, we've got you covered: <em>The Beginner's Guide to TypeScript</em> is available exclusively to newline Pro members. You can <a href="https://newline.co/pricing" rel="noopener noreferrer nofollow">join here</a>.</p><figure class="photo figure-position-inline"><img src="https://s3.amazonaws.com/assets.fullstack.io/n/20201208035942926_ts-email-hero.jpg" attachmentid="a01c14b8-28ee-410a-86c3-0150bfe2baa9" contenteditable="false" data-width="600" data-height="323"><div></div></figure><p></p><h2><a name="why-port-your-javascript-code-to-typescript" id="why-port-your-javascript-code-to-typescript">Why Port Your JavaScript Code To TypeScript</a></h2><p>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.</p><p><strong>This is a big deal because type errors are a significant, and frequent, source of bugs in just any codebase</strong>.</p><p>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.</p><p><strong>TypeScript helps solve the problem!</strong> </p><p>While testing doesn't go away, it's a massive help to have your editor inform you of any mismatched types as you code.</p><h2><a name="setting-up-typescript-in-your-existing-javascript-project" id="setting-up-typescript-in-your-existing-javascript-project">Setting Up TypeScript In Your Existing JavaScript Project</a></h2><p>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?</p><p>The first step in setting up TypeScript for your project is to create a folder structure with <code>src</code> and <code>dest</code> directories. Here, <code>src</code> is where you will write your TypeScript files. Likewise, <code>dest</code> is where your JavaScript files will be generated once TypeScript compiles your files in the <code>src</code> directory.</p><p><strong>Note, you can name these two directories anything you want, e.g. <code>built</code> for the <code>dest</code> directory.</strong></p><p>Next, create a <strong>TypeScript configuration file</strong>, named <code>tsconfig.json</code> in the root folder in your project.</p><p>It controls how TypeScript compiles your source files. Here is a basic <code>tsconfig.json</code> file.</p><textarea data-iscodemirror="true" data-mode="text/jsx" data-uniqueid="cm-l36ALgzx5oE1QMjLZHzEF" id="cm-l36ALgzx5oE1QMjLZHzEF">{
  "compilerOptions": {
    "outDir": "./dest",
    "allowJs": true,
    "target": "es5"
  },
  "include": ["./src/**/*"]
}</textarea><p>As you can see, the <code>include</code> section specifies where your source files reside. The <code>outDir</code> specifies where to place compiled files. The <code>target</code> is the JavaScript version you want to target.</p><p>Now you can compile TypeScript files into JavaScript by running the command <code>tsc</code> in the top level directory in your project.</p><h2><a name="convert-js-javascript-files-into-ts-typescript-files" id="convert-js-javascript-files-into-ts-typescript-files">Convert .js JavaScript Files Into .ts TypeScript Files</a></h2><p>You're now able to write new <code>.ts</code> and <code>.tsx</code> files in your previously JavaScript-only project, but how do you change existing JavaScript files to TypeScript?</p><p><strong>The good part about TypeScript is that you don't <em>have</em> to! You can keep existing JavaScript files in your source files and only convert them gradually to TypeScript.</strong></p><p>To convert a JavaScript file into TypeScript, change the file extension from <code>.js</code> or <code>.jsx</code> to the TypeScript equivalent: <code>.ts</code> or <code>.tsx</code>.</p><p><em>You might see some errors when TypeScript compiles, because there might be missing types in your new <code>ts</code> files. However, by default, TypeScript will still compile and output the <code>.js</code> files in spite of any errors.</em></p><p>To fix errors, add the types where they are missing, e.g :</p><ul><li><p>in functions </p></li><li><p>in variables </p></li><li><p>in arguments to functions </p></li><li><p>etc.</p></li></ul><h2><a name="adding-types-to-functions" id="adding-types-to-functions">Adding Types To Functions</a></h2><p>To convert JavaScript functions into TypeScript functions, you must add types to the arguments as well as specify the return type.</p><p><strong>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.</strong></p><p>Here's a sample JavaScript function we want to convert into TypeScript:</p><textarea data-iscodemirror="true" data-mode="text/jsx" data-uniqueid="cm-tFPXuwoXGIxSB4EEzg5Zq" id="cm-tFPXuwoXGIxSB4EEzg5Zq">let add = function (x, y) {
    return x + y;
};</textarea><p>Here is how it looks in TypeScript when we add full type annotations to the function.</p><textarea data-iscodemirror="true" data-mode="text/jsx" data-uniqueid="cm-ELu-9GX6sVLl3pvM128hB" id="cm-ELu-9GX6sVLl3pvM128hB">let add: (
  a: number,
  b: number
) =&gt; number = function (x: number, y: number) {
  return x + y;
};</textarea><p>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:</p><textarea data-iscodemirror="true" data-mode="text/jsx" data-uniqueid="cm-L8pkt3GhOmy7_DphrLDPI" id="cm-L8pkt3GhOmy7_DphrLDPI">let add = function (
  x: number,
  y: number
): number {
  return x + y;
};</textarea><p><em>On compilation, this produces exactly the same JavaScript ouput in both cases.</em></p><h2><a name="installing-types-for-dependencies" id="installing-types-for-dependencies">Installing Types For Dependencies</a></h2><p>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.</p><p>To get these benefits, you must install the type definitions for the package you want to use.</p><p>Suppose you want to use the <code>react</code> package. You can install its type definitions from NPM by running the command:</p><p><code>npm install --save @types/react</code></p><p>If you need types for a particular package, check <a href="https://www.npmjs.com/~types" rel="noopener noreferrer nofollow">NPM</a> for the type definitions.</p><h2><a name="best-practices-and-troubleshooting" id="best-practices-and-troubleshooting">Best Practices And Troubleshooting</a></h2><p><em>You might run into problems as you go about porting your JavaScript project to TypeScript.</em></p><p>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 <em>The Beginner's Guide to TypeScript</em> and it's available <em>exclusively</em> to <a href="https://newline.co/pricing" rel="noopener noreferrer nofollow">newline Pro members</a>.</p><p>It's written by Christian Santos, a Facebook engineer, who has used TypeScript extensively in his work.</p><h2><a name="typescript-boilerplates" id="typescript-boilerplates">TypeScript Boilerplates</a></h2><p>If you use Angular or React, both of these frameworks have TypeScript support built in.</p><ul><li><p>create-react-app supports a typescript flag, which generates your project using TypeScript</p></li><li><p>Angular is TypeScript by default</p></li></ul><p>If you're creating a Node.js project, <a href="https://github.com/microsoft/TypeScript-Node-Starter" rel="noopener noreferrer nofollow">Microsoft ships a Node.js Starter</a>.</p><p>If you're creating a library, a package I've used a bunch of times is <a href="https://github.com/formium/tsdx" rel="noopener noreferrer nofollow">tsdx</a> which gives you a great zero-config starter for TypeScript package development.</p><p></p>

Learn

The newline Guide to Building Your First GraphQL Server with Node and TypeScript

Teach

Amelia Wattenberger

Author of Fullstack D3

Community

How To Port A JavaScript Project To TypeScript

Tags

Responses (0)

Masterclasses

Tutorials

Fullstack React with TypeScript