Add Type Definitions To An External JavaScript File In TypeScript

Not too long ago I wrote an article that explained how to include external JavaScript libraries in an Angular TypeScript project. To summarize that post, my goal was to show how to use any of the millions of JavaScript libraries that exist online within a TypeScript application. I received a lot of heat from that article saying that I am missing the point of TypeScript because in the end I wasn’t using any type definitions. I disagree because not every library that exists on the internet will have a set of type definitions. In that sense the article still proves very useful.

This time around, I want to explain how to include type definitions in your project, should they exist. I won’t be going over the entire Angular demo again, but the JavaScript library will be the same and it will still be a functional application.

UPDATE 03/06/2017: While the information below is still valid, I’ve created a revisited article that has a different set of examples and an even more modern set of code. I recommend following along with the information below regardless.

In this article we’re going to look at the jsSHA hashing library created by Brian Turek. We won’t be creating a web application, but our code will be runnable through Node.js.

With that said, create the following directories and files. I’ll be using my Terminal (Mac and Linux) for convenience. You can use the same or your Command Prompt (Windows).

mkdir TypingsProject
touch TypingsProject/main.ts

Although we can start coding our project, we won’t be able to do anything with it yet and our editor will likely not recognize the TypeScript. Going forward, assume that my Terminal has TypingsProject as the current working directory. Let’s start by creating a Node Package Manager (NPM) package file in that directory with the appropriate dependencies:

npm init --y
npm install typescript jssha --save

This will create the package.json file with the TypeScript and jsSHA dependencies.

Now we can create our TypeScript configuration for the project. This will allow our IDE of choice to check for code correctness and give possible autocomplete features. To create this file, execute the following:

tsc --init

So far so good!

As of right now the jsSHA library will have no type definitions. When trying to use this library in your project, your IDE and compiler will likely throw all kinds of errors. You can use the declare keyword like I explained in the previous tutorial, but where is the fun in that?

Instead, we need to install a package called Typings. This is installed with NPM and although you don’t have to install it globally on your machine, I am choosing to. It can be installed like so:

npm install -g typings

Now we can install the jsSHA type definitions. From your Command Prompt or Terminal, execute the following:

typings install jssha --save --ambient

This will not only create a typings.json file in your project, but also a directory with the appropriate typing files. The good news though is that we’re ready to code at this point.

Open your main.ts file and include the following code:

import * as jsSHA from "jssha";

class sha {

    shaObj: any;
    hash: string;

    constructor() {
        this.shaObj = new jsSHA("SHA-512", "TEXT");
        this.shaObj.update("This is a test");
        this.hash = this.shaObj.getHash("HEX");
    }

}

var s: any = new sha();
console.log("Hash: " + s.hash);

In the above chunk of code, the first thing we do is import the jsSHA library. After, we create a simple class called sha which will take a constant string and hash it.

Since this project is more of a script we will make use of this class and print out the public hash variable. To run this file, execute the following:

node main.js

Notice I am running the JavaScript file, not the TypeScript file. If this file was not automatically created by your IDE, you may need to do other configurations. Otherwise just run tsc to compile the TypeScript file beforehand.

Conclusion

When working with a TypeScript project, whether that be Angular or something else, you’re probably going to want to have type definitions for everything you use that is found externally to your project. These definitions can easily be included in your project through the Typings package.

Keep in mind that not all JavaScript libraries that exist on the internet will have type definitions. In those scenarios, visit my other tutorial on the topic.

A video version of this article can be seen below.

Nic Raboy

Nic Raboy is an advocate of modern web and mobile development technologies. He has experience in C#, JavaScript, Golang and a variety of frameworks such as Angular, NativeScript, and Unity. Nic writes about his development experiences related to making web and mobile development easier to understand.