Creating a TypeScript Declaration File

Definitely Typed

When using TypeScript, sooner or later you will come across an NPM package that doesn’t have any type definitions. What does that mean for you? No type safety, compilation errors and no auto-complete. That is what a declaration (or a .d.ts) file is for, which basically describes the JavaScript library to TypeScript.

Installing a declaration file

Most packages should ship with a declaration file, e.g. moment. Here, this package will come with the file moment.d.ts which will provide TypeScript with the ability to understand the library.

Now, if a package doesn’t come with a declaration file, someone else, i.e. not the maintainers of the package, may have created it and you can find it in the NPM library for @types. For example, the Bootstrap Datepicker package doesn’t come with a declaration file, but there does exist one here.

To install this declaration file, simply execute the following command:

  npm install @types/bootstrap-datepicker

or if using yarn

  yarn add @types/bootstrap-datepicker

Which will add the declaration file to your node_modules/@types folder.

Creating your own declaration file

So, if a package doesn’t come with a declaration file, and it doesn’t exist within NPM @types, you should create a declaration package for it. This is very simple. The GitHub repo for the declaration files is located here.

For this example, we’ll create the declaration file for the this (jquery-toast-plugin) package. Guidelines dictate that you should name the @types package after the package itself, so this will be jquery-toast-plugin in our case.

1. First, you’ll want to fork the DefinatelyTyped repo.

2. Creating the files. Every type package has the following 4 files:

index.d.ts – the declaration file

jquery-toast-plugin-tests.ts

tsconfig.json

tslint.json

Which will reside in the types/ jquery-toast-plugin folder (there’s not need to create any of this manually). Microsoft have created a very nice TypeScript Definition file generator package to help creating these files. To create these 4 files, while in the types folder, execute the following to get dts-gen installed globally:

npm install -g dts-gen

Next, install your package:

  npm install jquery-toast-plugin

Go into your types folder and execute the following:

  dts-gen --dt --name jquery-toast-plugin --template module

This will create the 4 files you require. The declaration file will be based on a template, but you can have it generated from the JavaScript library. Go into your type folder, jquery-toast-plugin in this case, and run:

  dts-gen -m jquery-toast-plugin -overwrite

This will generate the .d.ts file for you. This is a good tool, but the generator won’t figure everything out, e.g. it’ll use any as many return and parameter types. Of course, you can then go into this declaration file and amend as required, or even write it from scratch, up to you.

There are many options available with the TypeScript Declaration file generator which I’ll let you explore yourself.

1. Finally, you need to add tests.

These aren’t tests that will be run but will be type checked. For jquery-toast-plugin, you’d simply need the following test:

  $.toast({ text: "test" })

1. Follow the guidelines. Run npm test and npm run lint jquery-toast-plugin to run all the ‘checks’ on your type package. This will run linting to make sure your code has been written to the standards set by Microsoft, e.g. the version comment is correct, braces are correctly positioned, white spacing etc.. There are also many other instructions, do and don’ts that you should try to following, which can be found here.

2. Create a pull request a wait for a maintainer to merge, after which, your type package will be available via npm!

Happy coding!