Wiring TypeScript Into React

A few weeks ago I delivered a session in ReactNext 2018 conference with the same title like this post’s name. Due to a lot of interest about the topic and questions I got as a result of the session, I decided to put the details I mentioned in my session in this Blog post.

In this post I’ll explain only the technical stuff about how to add TypeScript to your existing React app. If you wish to learn the reasons to use TypeScript or about TypeScript support in create-react-app, you can watch the session recording here:

What We Are Trying To Do?

If you are starting a new project, create-react-app already includes the option to start a project with TypeScript. In order to do that just run create-react-app with the --scripts-version=react-scripts-ts flag and your project will be created with TypeScript wired for you. From then you can proceed and work on your app.

But most of us aren’t starting new projects every day. That means that either you are maintaining a React app right now or developing a React app without TypeScript. What if you want to add TypeScript support to your existing app. This is where the next steps will help you to do exactly that.

Adding TypeScript and a TypeScript Webpack Loader

First thing first, you will add TypeScript to your project. Open command line and get into the root folder of your project. Run the following command to install TypeScript and awesome-typescript-loader:

npm install --save-dev typescript awesome-typescript-loader

awesome-typescript-loader is a commonly used Webpack loader that enables to compile and add TypeScript transpiled files to your JavaScript Webpack build.

Note: If you aren’t using Webpack, add a bundler loader that can transpile TypeScript to JavaScript to your project.

You can notice that I’m not installing TypeScript globally (using -g flag). The reason is that in each project I want to manage my TypeScript version. Relaying on a global installation might introduce TypeScript compilation errors if there are version mismatches or breaking changes in definition files. Since both TypeScript and awesome-typescript-loader are used for development I use the — save-dev flag to add the dependencies as development dependencies.

Adding the React Typings

After you installed TypeScript and it’s loader it’s time to add typings to your project. Every major library/framework has TypeScript typings, which are definitions files that TypeScript uses to understand all the library/framework type system. These definition files are postfixed with .d.ts and can be downloaded using npm from the “@types” repository. React, React-DOM and PropTypes have typings, so in order to install them use the following command:

npm install --save @types/react @types/react-dom @types/prop-types

If you have other dependencies add their typings as well. Omitting the step of adding typings will probably result in compilation errors when you work with React or any other library/framework.

Adding The TypeScript Configuration File

Now that you have TypeScript and the relevant typings in the project, you can move forward and configure the TypeScript compiler. In order to configure TypeScript compiler you need to have a tsconfig.json file in your project’s root folder. Add the new file and put the compiler configuration options that you what to enforce in the project. The following code is an example of a tsconfig.json file:

{
 "compilerOptions": {
 "outDir": "./dist/",
 "sourceMap": true,
 "module": "commonjs",
 "target": "es5",
 "jsx": "react"
 },
 "include": [
 "./src/\*\*/\*"
 ]
}

The only important configuration that you should add to the compilerOptions part for React development is "jsx": "react" (which is marked in bold in the example). This option helps TypeScript compiler to understand JSX, which is used inside React components.

Configuring Webpack to Build TypeScript

The last thing that you will have to do to enable TypeScript in your app is to add a build step in Webpack that transpiles TypeScript code to JavaScript code.

Note: If you use another bundler, wire the loader you installed in the first step into the bundler build. In this example I’m showing how to do it with Webpack.

In order to add TypeScript to Webpack build process you will add the awesome-typescript-loader loader in the Webpack rules. You should test for .ts and .tsx files and compile those files into JavaScript using awesome-typescript-loader. An example of a webpack.config.js file can look like:

const path = require('path');
const webpack = require('webpack');

module.exports = {
 entry: './index.js',
 mode: 'development',
 output: {
   path: path.resolve(\_\_dirname, 'build'),
   filename: 'bundle.js'
 },
 resolve: {
   extensions: [".ts", ".tsx" , ".js", ".json"]
 },
 module: {
   rules: [
     { test: /\.tsx?$/, loader: "awesome-typescript-loader" } ,
     { test: /\.js$/, loader: 'babel-loader', query: { presets: ['es2015', 'react'] }}
   ]
 },
 stats: {
   colors: true
 },
 devtool: 'source-map'
};

I’ve marked the things that you should add to the configuration file in bold.

After doing all the steps your project should be ready to use TypeScript.

Congratulation!

Go ahead and add a React component using .tsx file and then compile the project and run it to test that everything works as expected.

Summary

In the post I explained how to add TypeScript into an existing React app which uses Webpack. Mainly, you will add TypeScript to the project, add a TypeScript build step into Webpack (or your project bundler) and just work with TypeScript in your app.

If you have any comments, feel free to add them in the comments section :)