Using Declaration Files for JavaScript Libraries

When working with JavaScript libraries in a TypeScript project, it is important to have proper type definitions in order to benefit from TypeScript's static type checking and intelligence features. This is where declaration files come into play. Declaration files provide type information for existing JavaScript code, allowing TypeScript to understand and provide accurate suggestions for library usage.

What are declaration files?

Declaration files have a .d.ts extension and contain type declarations for existing JavaScript code. They provide the necessary information about the library's structure, methods, and variable types, allowing the TypeScript compiler to recognize the library's API and provide accurate type checking and auto-completion.

Types of declaration files

There are two main types of declaration files: global and module.

Global declaration files

Global declaration files are used to define global variables and types that are accessible throughout the entire application. They allow you to declare types for libraries that modify the global scope, such as jQuery, AngularJS, or Node.js.

To use a global declaration file, you simply need to include it in your TypeScript project. TypeScript will automatically recognize the declaration file and provide the appropriate type checking and suggestions.

Module declaration files

Module declaration files are used to provide type information for JavaScript modules. They are particularly useful for libraries that are designed to be imported and used as modules, such as lodash or axios.

To use a module declaration file, you need to reference it inside your TypeScript file using triple-slash directives. For example, if you have a declaration file named lodash.d.ts, you can reference it like this:

/// <reference path="./lodash.d.ts" />

This will make TypeScript aware of the types defined in the declaration file and provide proper type checking and suggestions when using the library.

Generating declaration files

Many popular JavaScript libraries provide their own declaration files, which can be installed via package managers like npm or yarn. These declaration files are usually maintained by the library authors themselves, ensuring that they stay up to date with the library's API.

If a declaration file is not available for a particular library, you can generate your own declaration file using the --declaration compiler flag or by using tools like dts-gen. However, manually creating declaration files can be a complex and time-consuming task, especially for large libraries.

Using DefinitelyTyped

DefinitelyTyped is a community-driven repository that hosts declaration files for thousands of JavaScript libraries. It is the most comprehensive collection of declaration files available and covers a wide range of libraries, from popular frameworks to niche utility packages.

To use DefinitelyTyped, you can install the package declaration files using a package manager like npm or yarn. For example, to install the declaration files for the lodash library, you can run:

npm install --save-dev @types/lodash

Once installed, TypeScript will automatically detect the declaration files and provide accurate type checking and suggestions when using the library.


Declaration files are essential when working with JavaScript libraries in a TypeScript project. They provide the necessary type information for libraries, enabling TypeScript's static type checking and intelligent auto-completion. Whether using global or module declaration files, or relying on community-driven repositories like DefinitelyTyped, declaration files allow developers to harness the full power of TypeScript while working with existing JavaScript code.

noob to master © copyleft