How to add type definitions to a TypeScript project

typings

TLDR: Use typings install –ambient <name of framework> to install type definitions

UPDATE: TypeScript 2.0 was released on Sept. 22, 2016

The code for this project can be found in this repository.

I’m still pretty new to TypeScript and trying to get the hang of things. One thing I’ve had a difficult time with is getting type definitions. Most of the blog posts I could find point me towards DefinitelyTyped, a repository for TypeScript definitions. Unfortunately, this is out of date, and NPM notifies you of this when you try to install it with the command npm install -g tsd .

definitely-typed-out-of-date

Instead, you’re encouraged to use Typings.

I then used the following command to install Typings:

# Install Typings CLI utility.
npm install typings --global

Afterwards, you’ll be greeted with this message, notifying you that it’s installing:

# Install Typings CLI utility. npm install typings --global

Typings or DefinitelyTyped?

Now here’s where things get confusing. I can find any package I need from Definitely Typed. I can just enter TSD install jquery and it will locate, download, and install that type definition at typings/jquery/jquery.d.ts.

tsd-install-jquery

Works well! So why does DefinitelyTyped say to use Typings? Even more bizarre, if you try to search for which type definitions are available to typings, it only lists these:

typings-searchI know what you’re thinking — “It’s only displaying a short, alphabetical list”, which is what I thought too. So let’s search for jQuery, the most popular JavaScript framework / library in the world:

typings install npm jquery

typings-install-jquery

Yeah, it’s not there.

But wait…. what is this noise about using “–ambient”? I don’t even know what that is.

typings install --ambient jquery

typings-ambient-jquery

What? Seriously?!

So it got the jQuery type definition from the remote DefinitelyTyped repository, and installed it in my local project.

typings-directory

Probably not the command I would have used to install it, but it is what it is.

Referencing the type definition from within your TypeScript file

One last step! You need to make your TypeScript file aware of the definitions. In my case, I’m creating a file called map.ts, and I need to add the reference to jQUery within it. Without this reference, TypeScript will throw a warning, stating that it doesn’t know what the $ means.

select-all-jquery

Now, I add the reference at the top of my map.ts file, and that red squiggly goes away!

/// <reference path="../../typings/main/ambient/jquery/jquery.d.ts" />

Note that the ../../ are escape sequences, so that I can navigate to the correct directory. It is basically saying “Right now I am located two folders deep in this project. I need to back out two folders, which brings me into the root directory. From there I can go to typings/main/ambient/jquery/jquery.d.ts“.

This is because my map.ts file is located inside of public/js folder, so I need to escape those and get back to the root directory.

jquery-typings-working

Conclusion

I wrote this because the instructions were not clear at all, on either the Typings site or DefinitelyTyped. If you could this to be helpful, please let me know. I’ll continue to blog about my trials and tribulations into the world of TypeScript from here! The code for this project can be found in this repository.

You can find more of my TypeScript tutorials here. 

-----------------------


subscribe-to-youtube

14 thoughts on “How to add type definitions to a TypeScript project

    • I figured there had to be other people with a similar issue. I’m not the smartest person, but when I saw how long it took me to wrap my head around this, I knew something was poorly documented.

  1. Hey David, I suggest to change the link on the first DefinitelyTyped. 🙂
    Also I think in order to install jQuery, at this hour, using Typings you need to write this in the CLI:
    typings install jquery=dt~jquery -G
    Because at the current version of Typescript all the external modules are installed globally so you’re not required to use the “–ambient” option in the command, but you need to specify a for the repo from where should install.

    So in my command I use:
    typings install jquery(as the name of the module) =dt(this is the repo location)~jquery(module’s repository folder) -G (Install and Persist as an Global definition)

    More details are in the help: typings install -h

    • Great find! Thanks for pointing that out, first link is now corrected.

      The joys of the ever-changing JavaScript landscape. What I’m going to do is edit the page, and reference your comment so that users have the option of using either one, in case they are using an older version.

      Thank you again for pointing this out!

  2. Just spent the last 45 minuets trying to figure this out.. Finally came across your post, which was exactly what I was looking for! A clean, clear, and easy to understand explanation. Thank you very, very much!!

    • Glad I could help. This thing had me stuck for days, to the point where I believed TypeScript was broken. It’s not. It’s just poorly documented :).

      This is *by far* the most trafficked blog post that I have, as well.

    • Sure thing. So that I don’t make any mistakes in the translation here, could you write exactly how the code should appear in this comment?

Leave a Reply