Is it possible to generate TypeScript declaration files from JS library?

If you have ever worked with JavaScript libraries in your TypeScript projects, you may have encountered situations where you needed type information for those libraries. TypeScript declaration files, denoted with the .d.ts extension, provide type information for JavaScript code, enabling better static type checking and editor support in TypeScript projects.

In this tutorial, we will explore different scenarios and methods for generating TypeScript declaration files from JavaScript libraries. We'll cover scenarios such as generating declaration files for existing JavaScript libraries, generating declaration files for your own JavaScript code, and leveraging tools like dts-gen and tsc to generate declaration files automatically.

Generating Declaration Files for Existing JavaScript Libraries

Method 1: Manual Declaration Files

One approach to generate declaration files for existing JavaScript libraries is to create them manually. This method is useful when the library does not provide its declaration file.

Syntax

To create a manual declaration file, you need to follow this syntax −

declare module 'library-name' {
   // Declare the library's exports and types here
}

Example 1

Let's say we want to create a declaration file for the popular JavaScript library lodash. Here's an example of how the declaration file lodash.d.ts might look −

declare module 'lodash' {
   export function uniq≷T&g;(array: T[]): T[];
   export function compact≷T&g;(array: T[]): T[];
}

In this example, we declare two functions, uniq and compact from the lodash library, specifying the input and return types.

Example 2

Let's consider a scenario where we want to create a declaration file for the JavaScript library axios. This library provides a simple and powerful API for making HTTP requests.

Create a file named axios.d.ts and add the following content −

declare module 'axios' {
   export function get(url: string): Promise&g;any≷;
   export function post(url: string, data: any): Promise≷any&g;;
}

In this example, we declare two functions get and post, that make HTTP GET and POST requests, respectively using axios.

Method 2: Declaration File Generators

Another approach to generating declaration files for existing JavaScript libraries is to leverage tools specifically designed for this purpose. One such tool is dts-gen, a command-line tool provided by TypeScript.

To use dts-gen, follow these steps −

• Install dts-gen globally by running the following command −

npm install -g dts-gen

• Navigate to the root folder of the JavaScript library you want to generate declaration files for.

• Run dts-gen followed by the entry file of the library. For example −

dts-gen -m library-name -o

This command generates a declaration file named library-name.d.ts in the current directory.

Example

Let's say we want to generate a declaration file for the JavaScript library moment.js. This library is widely used for parsing, manipulating, and formatting dates and times.

To generate the declaration file for moment.js, follow these steps −

• Install dts-gen globally by running the following command −

npm install -g dts-gen

• Navigate to the root folder of the moment.js library.

• Run the following command to generate the declaration file −

dts-gen -m moment -o

This command generates a declaration file named `moment.d.ts` in the current directory.

Now you have a declaration file that provides type information for the moment.js library.

Generating Declaration Files for Your Own JavaScript Code

If you have JavaScript code that you want to convert to TypeScript, generating declaration files can be a helpful starting point. TypeScript provides a utility called tsc that can automatically generate declaration files from JavaScript code.

To generate declaration files using tsc, follow these steps −

• Install TypeScript globally by running the following command −

npm install -g typescript

• Create a tsconfig.json file in the root directory of your JavaScript project with the following configuration −

{
   "compilerOptions": {
      "allowJs": true,
      "declaration": true,
      "outDir": "dist"
   },
   "include": ["src"]
}

The allowJs option allows TypeScript to compile JavaScript files, the declaration option enables declaration file generation, and the outDir option specifies the output directory for the generated declaration files.

• Run the following command to generate declaration files for your JavaScript code −

tsc -p tsconfig.json

This command invokes the TypeScript compiler (tsc) and instructs it to use the tsconfig.json file for configuration. The compiler will then generate the declaration files based on the JavaScript code specified in the include section of the tsconfig.json file.

Example

Suppose you have a JavaScript file named utils.js containing utility functions. You want to generate a declaration file for these functions.

• Install TypeScript globally by running the following command −

npm install -g typescript

• Create a tsconfig.json file in the root directory with the following configuration −

{
   "compilerOptions": {
      "allowJs": true,
      "declaration": true,
      "outDir": "dist"
   },
   "include": ["src"]
}

• Run the following command to generate the declaration file −

tsc -p tsconfig.json

This command compiles the JavaScript code and generates corresponding declaration files in the specified output directory (dist in this example).

After running the command, you will find a utils.d.ts file in the dist folder containing the generated TypeScript declaration file for the utils.js code.

Conclusion

In this tutorial, we explored different methods for generating TypeScript declaration files from JavaScript libraries. We covered manual declaration file creation and the use of tools like dts-gen and tsc to automate the generation process. By leveraging these methods, you can enhance the type safety and maintainability of your TypeScript projects, enabling smoother collaboration and better error detection.

Remember to regularly update your declaration files as the JavaScript library or your code evolves to ensure accurate type information. Generating TypeScript declaration files empowers you to work effectively with JavaScript libraries in your TypeScript projects, providing better code editor support and catching potential errors early.