Finding and Writing Declaration Files

Finding declaration files

Now that we know what a declaration file is, how do we find one that matches the JavaScript library that we are trying to use? Soon after TypeScript was released, Boris Yankov set up a GitHub repository to house TypeScript declaration files for third-party libraries. This repository, named Definitely Typed, quickly became very popular and is now the go-to repository for declaration files.

One of the major issues that needed to be addressed in relation to declaration files was the need to match a particular JavaScript library version with the Definitely Typed version that matched that release. The community has, over time, built a number of command-line tools to help with this, including tsd, typings, and NuGet extensions.

As of version 2.0 of TypeScript, we are able to use npm to install declaration files. As an example of this, let’s install the underscore package and its corresponding types as follows:

npm install underscore
npm install @types/underscore --save-dev

Here, we use npm to install the JavaScript library underscore, and then we use npm to install the corresponding declaration files by prefixing the library name with @types/.

In fact, if we attempt to use a library without installing the associated @types declaration files, the TypeScript compiler will generate the following error.

Could not find a declaration file for module 'underscore'
Try `npm i --save-dev @types/underscore` if it exists or add a new declaration (.d.ts) file containing `declare module 'underscore';

The compiler tells us that we have attempted to use the underscore library without the associated declaration files.

Note that the compiler gives us two solutions here: the first is to install the @types declaration files if they exist, and the second is to create a new declaration file that just contains the following text:

declare module 'underscore';

Here, we declare that there is a module named 'underscore' that we wish to use, but we don’t provide a declaration file for it. This solution is really the last resort and should be avoided when possible.

The reason for this is that we will not have any types declared for this library, and it will just be of type any.

Note that over time, some JavaScript libraries have begun to include declaration files within their main package, and therefore, we do not even need to install an @types package in order to use it.

The popularity and usefulness of the Definitely Typed repository have meant that more and more contributors have written declaration files for just about every JavaScript library that we could wish to use.

In general, the only exception to this is when a particular library has had a major version upgrade and the types are lagging behind slightly.

Note: This popularity has also meant that the TypeScript team itself has included a tool for searching for types on their website named Type Search. Here, we can search for type declaration files and, as can be seen in the help text, declaration files that are either bundled or in the Definitely Typed repository.

Writing declaration files

As we have seen, in order to use JavaScript within a TypeScript project, we will need a declaration file that tells the compiler what functions or objects are made available and what types they are.

There may be times, particularly if we are working in a large, established code base, when we need to integrate some homemade JavaScript into our TypeScript project. In these cases, we will need to write a declaration file of our own.

Let’s assume that we need to integrate an existing JavaScript helper function into our TypeScript code.

As an example of this, consider the following JavaScript code: