Create TypeScript declarations from JavaScript and JSDoc

Even if you don't write your code in TypeScript you can still generate .d.ts files to provide more information to developer tools.

For a variety of reasons, I prefer to write my code in vanilla JavaScript with JSDoc comments rather than writing in TypeScript. Today’s smart code editors, like Visual Studio Code, are able to read type information from JSDoc and provide Intellisense options as you code. However, those consuming your code may not get the same benefit unless you include a TypeScript declaration file along with the source files. Fortunately, TypeScript allows you to generate type declaration files directly from JavaScript files and will use information in JSDoc comments to assign the appropriate types.

First, make sure you have TypeScript installed:

$ npm install typescript --save-dev

Then, create a tsconfig.json file with the following options:

    "include": [
    "compilerOptions": {
        "declaration": true,
        "emitDeclarationOnly": true,
        "allowJs": true

Make sure that include specifies the files you want to generate declaration files for. The compilerOptions are:

  • declaration - generate the declarations for the files specified
  • emitDeclarationOnly - only output .d.ts files and not source files
  • allowJs - expect the source files to be JavaScript

Now you can run tsc to generate your .d.ts files:

$ tsc

Or you can omit the tsconfig.json file and just pass the corresponding flags on the command line, like this:

$ tsc --allowJs -d --emitDeclarationOnly src/foo.js

In this example, tsc will output src/foo.d.ts.

Just make sure the declaration file(s) are part of the package that you are publishing by using the types field in your package.json file.

Understanding JavaScript Promises E-book Cover

Demystify JavaScript promises with the e-book that explains not just concepts, but also real-world uses of promises.

Download the Free E-book!

The community edition of Understanding JavaScript Promises is a free download that arrives in minutes.