Typings for TypeScript

When using TypeScript, you will need TypeScript definition files to work with external libraries. A lot of those definition files are available on GitHub: DefinitelyTyped. At the time of writing, there are 1708 entries which is to much to show, even for GitHub.

Let’s say you want to work with jQuery. If you look at the DefinitelyTyped folder for jQuery, you’ll find a couple of files:

jQuery-DefinitelyTyped

The extension .d.ts signals that the file is a TypeScript Definition file. To use these files in your project, you can choose to download the Definition file and copy it to your project. But manually downloading and searching for files doesn’t sound like the best option.

Fortunately, there is an easier way: Typings.

Using Typings for TypeScript

One scenario where I used Typings is while developing the open source Folder Management extension that you can find at GitHub.

The Folder Management project uses Node Package Manager to download external libraries that it uses. If you look at the package.json file you can see which packages are used in this application:

{
 "name": "folder-management",
 "version": "1.0.0",
 "description": "Microsoft DevLabs Folder Management extension",
 "keywords": [
 "vsts",
 "tfs"
 ],
 "scripts": {
 "initdev": "typings install",
 "copyfiles": "copyfiles -f node_modules/vss-sdk/lib/VSS.SDK.js node_modules/jquery/dist/jquery.min.js scripts/lib",
 "setup": "npm run initdev && npm run copyfiles",
 "package": "tfx extension create --manifest-globs vss-extension.json",
 "publish": "tfx extension publish --token <token> --manifest-globs vss-extension.json"
 },
 "author": "ALM Rangers",
 "license": "MIT",
 "devDependencies": {
 "copyfiles": "^0.2.1",
 "grunt": "~0.4.5",
 "grunt-cli": "^1.1.0",
 "grunt-contrib-copy": "~0.8.2",
 "grunt-exec": "~0.4.6",
 "grunt-typescript": "*",
 "jquery": "^2.2.2",
 "requirejs": "2.1.22",
 "tfx-cli": "^0.3.19",
 "tsconfig-glob": "^0.4.0",
 "typescript": "^1.7.5",
 "typings": "^0.6.6",
 "vset": "^0.4.24",
 "vss-web-extension-sdk": "^1.96.1"
 }
}

The dependency we’re now interested in is typings. Adding this line to your package.json makes sure that the typings library is downloaded to your node_modules folder. If you then look at the script sections you see a line named initdev that runs a typings install command.
The Task Runner Explorer shows the custom tasks that I defined in package.json. The initdev task is the one we’re interested in.

Task Runner Explorer - NPM tasks

When you run this script, typings looks for a typings.json file and starts downloading the definition files that you need. The typings.json file for Folder Management looks like this:

{
 "dependencies": { },
 "devDependencies": { },
 "ambientDevDependencies": {
 "Q": "github:DefinitelyTyped/DefinitelyTyped/q/Q.d.ts#4de74cb527395c13ba20b438c3a7a419ad931f1c",
 "jquery": "github:DefinitelyTyped/DefinitelyTyped/jquery/jquery.d.ts#470954c4f427e0805a2d633636a7c6aa7170def8",
 "knockout": "github:DefinitelyTyped/DefinitelyTyped/knockout/knockout.d.ts#4de74cb527395c13ba20b438c3a7a419ad931f1c",
 "tfs": "github:microsoft/vss-web-extension-sdk/typings/tfs.d.ts",
 "vss": "github:microsoft/vss-web-extension-sdk/typings/vss.d.ts"
 }
}

You configure a name and a url to each definition file that you want to have. In this case, I’m downloading the files for Q, jQuery, Knockout and the TFS and VSS sdks. The easiest ways to get the URL, is navigate to the file in GitHub and use the ‘Copy path’ button.

If you have the typings dependency downloaded through NPM and you have the typings.json file, you’re ready to run the typings install script. Running this script will give you a new folder named typings. In this folder, there is a main.d.ts file that references all your downloaded definition files. All you have to do, is add a reference to main.d.ts from your TypeScript files and you’re done.

Solution Explorer showing typings

And that’s all there is. Feel free to download the code from GitHub and open the solution in Visual Studio. You’ll then automatically download the NPM packages and be able to use the Task Runner to run the initdev script to download the typings.

Feel free to leave a comment!