If you haven’t already gotten involved with it, you’ll probably know that TypeScript is becoming increasingly popular. Being able to use a superset of javascript in a typed language that compiles down to JavaScript is a great thing. However,if you’ve ever played around with TypeScript and tried to use JavaScript libraries, you’ll probably know that sometimes it can be a real pain. Often JavaScript libraries do not ship with type definitions which are critical when it comes to playing nice with TypeScript.
If you’ve been keeping up with The Polyglot Developer you’ll probably remember two posts that were created. Previously I had written about including external JavaScript libraries in an Angular application as well as adding type definitions to external JavaScript libraries in TypeScript .
We’re going to revisit these two articles and explore all the ways to include JavaScript libraries in TypeScript applications. These include applications built with NativeScript , Ionic , and Angular .
We’re going to use a particular JavaScript library for the examples used throughout this particular article. This library is called base-64 and will handle base64 encoding and decoding without having to worry about atob and btoa . You have to remember that this library is a JavaScript library and was not built with TypeScript in mind.
Several different project examples will be created in an effort to keep things easy to understand.
Create a New Vanilla TypeScript Project
Thefirst project we create will use vanilla TypeScript and will be ran through Node.js. This means we won’t be using Angular, HTML, or anything else. We will create a TypeScript file, compile it, and run it via Node.js.
Create a new project directory and execute the following commands:
npminit --y tsc --init
The above two commands should leave us with a package.json file as well as a tsconfig.json file. The next step is to add the libraries we wish to use via the Node Package Manager (NPM):
npminstallbase-64 utf8 --save
The above command will add the base-64 library and its utf8 dependency. As of right now we have a few JavaScript dependencies and our project, but no source code to our application.
Create and open an app.ts file and add the following TypeScript code:
import * as base64from "base-64"; import * as utf8from "utf8"; var str = "nicraboy"; var bytes = utf8.encode(str); var encodedStr = base64.encode(bytes); console.log(encodedStr);
The above code was taken from the library documentation. However, if you try to compile this file by executing tsc , you’ll end up with errors that look like the following:
app.ts(1,25): error TS2307: Cannot find module 'base-64'. app.ts(2,23): error TS2307: Cannot find module 'utf8'.
The above is not something we want to see. So what if we altered the library imports to look like the following instead?:
var base64 = require("base-64"); var utf8 = require("utf8");
The above lines are what you’d typically see in a JavaScript application, not necessarily a TypeScript application. When we try to compile our application with the require statements, we end up with the following messages:
app.ts(1,14): error TS2304: Cannot find name 'require'. app.ts(2,12): error TS2304: Cannot find name 'require'.
The above lines are different errors, but still errors nonetheless. This is because the require function is a JavaScript thing, not a TypeScript thing.
So what do we do if we want to resolve these errors and use our library?
One solution would be to download type definitions for each of our libraries if they exist. An example of this would look like the following:
npminstall @types/base-64 @types/utf8 --save
If we download the type definitions we can continue to use the import statements that we saw previously. Execute the tsc command and it should compile without issues. You can test the project by executing the following:
nodeapp.js
However, what happens if the type definitions don’t exist or what if we’d like to use the require commands instead? We can actually obtain the type definitions for the require command so it becomes TypeScript compatible.
Install the following type definitions to use the require command:
npminstall @types/node --save
With the node type definitions we can use any JavaScript library in our TypeScript project without needing to find the relevant type definition files.
Using a Browser JavaScript Library in a TypeScript Project
If you’re developing web applications, you might run into a situation where you include a JavaScript library via a <script> tag that doesn’t play nice in your TypeScript code.
Let’s create a new project somewhere on our computer. We’re not going to create a Node.js project, but we will need to handle TypeScript. Execute the following:
tsc --init
We’ll also need an app.ts and an index.html file in our project. Finally, since this a browser based project, we need to download the base-64 library and utf8 library. This should leave you with a base64.js and utf8.js file in your project.