Photo by Christina @ wocintechchat.com on Unsplash
Using a JavaScript library inside an Angular project is not as straightforward as using it in Angular JS or a plain JavaScript project. In a plain JavaScript project, you can include the library in the scripttag of your index.html and then the library is available to use.
But in an Angular project, following the same steps might not actually work. In fact, the compiler may throw an error at the usage of the library. To include and use the library, the standard way would be to install the library using npm and then look for its type declaration file(*.d.ts). The library's type declaration file may or may not be part of its source code. If it's not present, it is required to be installed separately.
What is a Type Declaration file?
TypeScript being a typed language, declaration files add the necessary typings to the untyped JavaScript code. In simple words, a type declaration file gives the compiler the information about an imported member and what parameters it expects, what are its data types, return value, etc.,
To understand further, take a look at the below example:
Here, there's a function named person that accepts an Array and returns an Object.
The declaration file for this function will be:
The declaration files contain only the type information and not the function implementation. These are called Ambient Declarations.
Points to be noted about TypeScript declarations:
-
No function/class/variable implementation is present in declaration files.
-
No default parameters to the function.
-
*declare *keyword is used to tell that the actual implementation of this function/class/variable exists somewhere else.
-
Use *declare *keyword only for exported members or on the functions/class/variable that is meant to be used from this file. Do not use it on local variables inside a function.
-
VS Code adds the necessary IntelliSense and shows the proper auto-complete suggestions once the .d.ts file is included. Thus making the development easy and identifying the errors ahead of time.
To create a declaration file for a JavaScript file, use the command:
npx typescript script.js --declaration --allowJs --emitDeclarationOnly --outDir types
The above command creates a types/script.d.ts file.
To create a declaration file for a TypeSscript file, use the command:
tsc script.ts -d
Once the declaration files are created, you can include them in your Angular Project and start using them. You have to include the source code and its declaration file.
How to use the Library in Angular Project?
If you install a JavaScript library in your Angular project, you must have noticed the source folder contains a file with an extension .d.ts. Some of the libraries do not come with an in-built typings folder, instead, you have to install them manually using @typings via npm.
Let us take the example of a popular JS library: Moment.js
npm install moment --save
Now, check the moment library in node_modules folder.
Moment.js library
Moment.js comes with a typing file called moment.d.ts . Now we can directly use the library by using import statement in the ts file.
import moment from 'moment';
date = moment().format('MMM Do YY');
This displays the current date.
We'll try adding another library, CryptoJS.
npm install crypto-js --save
After installing, if you try to use the CryptoJS methods, the compiler will throw an error asking to install the type declaration file of CryptoJS. This library doesn't come with its type declaration file. We need to install it separately.
Thanks to the DefinitelyTyped community for publishing the typings for the libraries.
npm i @types/crypto-js --save-dev
The type declaration file once installed is recognized by the compiler and you can start using the methods.
import * as CryptoJS from 'crypto-js'
Now you can start using the library methods.
app.component.ts with Moment.js and CryptoJS libraries.
Bind the variables in the HTML page to see them.
Binding the component value to HTML
Conclusion
-
To use the JavaScript library in an Angular project, install the library via npm and check for its type declaration file.
-
Install the type declaration file from @types/
, if it is not a part of the source code. -
import the library in your component and start using it
.
Here's a working StackBlitz example for this.
References
https://www.typescriptlang.org/docs/handbook/2/type-declarations.html
That's all!
Hope this article was useful!