Migration to TypeScript

TypeScript is an open source language, based on JavaScript, which speeds up and improves the way how we write JavaScript code and reduces the number of errors. It provides many interesting functionalities such as static typing, enums, interfaces and much more.

In addition, it allows you to use ES6 functions such as the arrow function, let/const or classes without giving up support for older browsers that do not recognize these functions.

Looking at all the files in the project that are already written in JavaScript, for many people who are thinking about migrating to TypeScript, the whole process may seem overwhelming.

Fortunately, migration to TypeScript is not that complicated. To add TypeScript to our project, we need to follow these few steps.

1. Changing the extensions of all .js files to .ts

2. TypeScript installation

3. Adding the tsconfig.json file to the project

4. Integration with the project building tool

5. Adding external library definition files

File extensions

The first step is to change the extensions of existing files that you want to migrate to TypeScript.

Changing the extensions of existing files does not involve any changes to the code. Every JavaScript code is also valid TypeScript code, which means we can still use JavaScript code without using any of the features offered by TypeScript. This means that you don't have to migrate all files at once, and you can migrate little by little, file by file.

TypeScript installation

The next step is to install TypeScript. Assuming that we use npm (Node Package Manager) to manage packages in the project, we can use it to install Typescript locally:

npm install typescript

or globally, allowing TypeScript to be used in every projects:

npm install -g typescript

tsconfig.json file

The tsconfig.json file contains the options used during compverting TypeScript code to JavaScript.

To create the tsconfig.json file, open a command prompt and go to the project directory, then run the following command:

tsc --init

You should receive a message indicating that the tsconfig.json file was created.

Integration with the project building tool

Most JavaScript projects use project building tools, such as gulp, grunt or webpack. Regardless, which we use in our project, each of these tools has plugins that allow you to compile TypeScript code into JavaScript. In this article we will focus on gulp.

Gulp is a set of tools for automating time-consuming programming tasks, such as building a project, checking code quality, running tests, etc.

Let's consider the following example of the gulpfile.js file:

const {src, dest} = require('gulp');
const concat = require('gulp-concat');
const inject = require('gulp-inject');

gulp.task('default', function () {
    var js = src(['src/app.js', 'src/home.js'])
    .pipe(concat('app.js'))
    .pipe(dest('./dist/'));

    return src('src/index.html')
    .pipe(inject(js, { ignorePath: 'dist/', addRootSlash: false }))
    .pipe(dest('dist/'));
});

The above configuration combines the two files src/app.js and src/home.js, the result is saved in the dist/app.js file, and then adds the <script> tag loading the dist/app.js file to the index.html file.

To integrate TypeScript with gulp we use the gulp-typescript plugin:

npm install gulp-typescript

Once we have the necessary plug-in, we're going to update the gulpfile.js file:

const {src, dest} = require('gulp');
const concat = require('gulp-concat');
const inject = require('gulp-inject');
const ts = require('gulp-typescript');
const tsProject = ts.createProject('tsconfig.json');

gulp.task('default', function () {
    var js = src(['src/app.ts', 'src/home.ts'])
    .pipe(tsProject())
    .pipe(concat('app.js'))
    .pipe(dest('./dist/'));

    return src('src/index.html')
    .pipe(inject(js, { ignorePath: 'dist/', addRootSlash: false }))
    .pipe(dest('dist/'));
});

The above example compiles the TypeScript code in the src/ directory into JavaScript and writes the result of this compilation to the dist/ directory.

After successfully compiling the code from TypeScript into JavaScript, the compiler may return several project-related errors. Many of them can be turned off using the proper flag configuration in the tsconfig.json file or simply repaired for example by adding any annotations.

Type definitions

Now, when compiling from TypeScript to JavaScript works fine, it's worth considering adding external library type definitions that we use, e.g. angular, lodash, jquery, etc. Type definitions make it easier to write TypeScript code by suggesting syntax. Many TypeScript type definition files are now available on DefinitelyTyped.

npm install @types/angular
npm install @types/lodash

Sourcemaps

In projects using TypeScript, the JavaScript code executed by the browser is different from the original code created by the programmer. In such situations, it is much easier to debug the original TypeScript code than the converted JavaScript code.

To generate source maps we will use gulp-sourcemaps:

npm install gulp-sourcemaps

To generate source maps, use two init() and write() methods:

const {src, dest} = require('gulp');
const concat = require('gulp-concat');
const inject = require('gulp-inject');
const ts = require('gulp-typescript');
const tsProject = ts.createProject('tsconfig.json');
const sourcemaps = require('gulp-sourcemaps');

gulp.task('default', function () {
    var js = src(['src/app.ts', 'src/home.ts'])
    .pipe(sourcemaps.init())
    .pipe(tsProject())
    .pipe(concat('app.js'))
    .pipe(sourcemaps.write())
    .pipe(dest('./dist/'));

    return src('src/index.html')
    .pipe(inject(js, { ignorePath: 'dist/', addRootSlash: false }))
    .pipe(dest('dist/'));
});

Summary

• TypeScript is a JavaScript extension that adds additional functions such as static typing, interfaces and enums, and enables the use of ES6 functions
• migration to TypeScript involves several steps:
  • Changing the extensions of all .js files to .ts
  • TypeScript installation
  • Adding the tsconfig.json file to the project
  • Integration with the project building tool
  • Adding external library definition files
• The tsconfig.json file contains the options used during converting TypeScript code to JavaScript
• You can use the gulp-typescript plugin to integrate TypeScript with gulp
• Type definitions make it easier to write code in TypeScript by syntax prompting
• Source maps allow you to debug the original TypeScript code even though the browser uses the converted JavaScript code