Typescript – How to produce a .d.ts “typings” definition file from an existing JavaScript library

tsctypescript

I'm using a lot of libraries both my own and 3rd party. I see the "typings" directory contains some for Jquery and WinRT… but how are they created?

Best Solution

There are a few options available for you depending on the library in question, how it's written, and what level of accuracy you're looking for. Let's review the options, in roughly descending order of desirability.

Maybe It Exists Already

Always check DefinitelyTyped (https://github.com/DefinitelyTyped/DefinitelyTyped) first. This is a community repo full of literally thousands of .d.ts files and it's very likely the thing you're using is already there. You should also check TypeSearch (https://microsoft.github.io/TypeSearch/) which is a search engine for NPM-published .d.ts files; this will have slightly more definitions than DefinitelyTyped. A few modules are also shipping their own definitions as part of their NPM distribution, so also see if that's the case before trying to write your own.

Maybe You Don't Need One

TypeScript now supports the --allowJs flag and will make more JS-based inferences in .js files. You can try including the .js file in your compilation along with the --allowJs setting to see if this gives you good enough type information. TypeScript will recognize things like ES5-style classes and JSDoc comments in these files, but may get tripped up if the library initializes itself in a weird way.

Get Started With `--allowJs`

If --allowJs gave you decent results and you want to write a better definition file yourself, you can combine --allowJs with --declaration to see TypeScript's "best guess" at the types of the library. This will give you a decent starting point, and may be as good as a hand-authored file if the JSDoc comments are well-written and the compiler was able to find them.

Get Started with dts-gen

If --allowJs didn't work, you might want to use dts-gen (https://github.com/Microsoft/dts-gen) to get a starting point. This tool uses the runtime shape of the object to accurately enumerate all available properties. On the plus side this tends to be very accurate, but the tool does not yet support scraping the JSDoc comments to populate additional types. You run this like so:

npm install -g dts-gen
dts-gen -m <your-module>

This will generate your-module.d.ts in the current folder.

Hit the Snooze Button

If you just want to do it all later and go without types for a while, in TypeScript 2.0 you can now write

declare module "foo";

which will let you import the "foo" module with type any. If you have a global you want to deal with later, just write

declare const foo: any;

which will give you a foo variable.

Quick and Dirty

If you just have one file using require, or you're doing this for demo purposes you can define require at the top of your TypeScript file.

declare var require: any

TypeScript 2.x

If you are using TypeScript 2.x you no longer need to have Typings or Definitely Typed installed. Simply install the following package.

npm install @types/node --save-dev

The Future of Declaration Files (6/15/2016)

Tools like Typings and tsd will continue to work, and we’ll be working alongside those communities to ensure a smooth transition.

Verify or Edit your src/tsconfig.app.json so that it contains the following:

...
"types": [ "node" ],
"typeRoots": [ "../node_modules/@types" ]
...

Make sure is the file in the src folder and no the one on the root app folder.

By default, any package under @types is already included in your build unless you've specified either of these options. Read more

TypeScript 1.x

Using typings (DefinitelyTyped's replacement) you can specify a definition directly from a GitHub repository.

Install typings

npm install typings -g --save-dev

Install the requireJS type definition from DefinitelyType's repo

typings install dt~node --save --global

Webpack

If you are using Webpack as your build tool you can include the Webpack types.

npm install --save-dev @types/webpack-env

Update your tsconfig.json with the following under compilerOptions:

"types": [
      "webpack-env"
    ]

This allows you to do require.ensure and other Webpack specific functions.

Angular CLI

With CLI you can follow the Webpack step above and add the "types" block to your tsconfig.app.json.

Alternatively, you could use the preinstalled node types. Keep in mind this will include additional types to your client-side code that are not really available.

"compilerOptions": {
    // other options
    "types": [
      "node"
    ]
  }

Typescript – How to install .d.ts file from github:DefinitelyTypes using typings

To install angular-formly definitions from DefinitelyTyped, use the following command:

typings install angular-formly --ambient

It's taken directly from here: Quick Start

EDIT: Because this is the accepted answer and syntax has changed, as of typings 1.0:

typings install dt~angular-formly --global