How to manage type definition files for third party libraries for your Typescript project

Mihai Coman
Aug 9, 2017 · 4 min read

Side note: type definition files are the solution to make Typescript code interact with plain Javascript code (for example, from third-party libraries). The closest equivalent I can think of is C/C++ header files. For the purpose of this article, I will assume you know what Typescript type definition files are, since you are looking for a way to manage them.

At Jexia, we are currently using Typescript to develop our Javascript SDK. The reasons behind this choice make the subject of a blog post of its own, however I feel that the choice is already quite well analyzed in public posts by other developers that faced it. Instead, I am going to talk about one aspect of using Typescript that I feel is not properly documented or easy to understand for a developer new to the language. I know it took me quite a bit of research until it finally clicked, so here’s the story! If you only want the solution, scroll down to the TL;DR.


A bit of history

First off, we need to consider that Typescript is an ever evolving language. And its evolution is pretty fast: the first version was released in mid 2014, 3 years ago. In this timespan, Typescript evolved, the adoption rate exploded and along with the language, an entire ecosystem evolved, including the tools that make a Typescript developer’s life easier. One of those tools is the type definition manager.

At first, typedef file management was manual. The DefinitelyTyped github repo was formed to host the typedef files, but was quickly overrun with the amount of public Javascript libraries that developers were writing Typescript typedef files for. TSD was built to work as a management tool to be used in development environments for automatic typedef file management, similar to how package managers work. After a while, due to changes to how the typedef files worked and changes to developers’ needs, Typings was built to replace TSD. Keep in mind these were all tools made by the open source community, not by Microsoft themselves and they were separate dev dependencies that one needed to bring into a Typescript project and learn how to use.

Microsoft’s solution

Microsoft finally released an officially supported mechanism for typedef file management with Typescript 2.0. The solution they implemented was to create a NPM organization and use the @types scope to define the type definition file packages (for more detailed info on how this NPM feature works see the official documentation). This way, installing a typedef file would look as simple as this:

npm install --save @types/<library_name>

Of course, this saves the type definition dependency into your package.json file. Installing type definition files for a Typescript project would now be handled along with installing the rest of the dependencies, with a simple npm install command after cloning the repository. Pretty cool.

In a blog post about type definition files, the Typescript team explains that this is the official mechanism going forward and also clears up the slightly confusing situation with the different typedef file management tools out there:

“For those wondering, DefinitelyTyped will still be the place to author new declaration files. We’ll soon be providing a greatly expanded set of documentation aimed at .d.ts authors in the near future. Tools like Typings and tsd will continue to work, and we’ll be working alongside those communities to ensure a smooth transition.”

The last piece of the puzzle is that the Typescript compiler also offers ways of customizing this functionality. So adding some options to your tsconfig.json file will allow you to fine tune where the typedef files are loaded from, on a library to library basis.

So what’s the problem?

The problem that I think developers new to Typescript face is that, even though the officially supported mechanism has been in place for about half a year, the official documentation doesn’t really put an emphasis on it, the information about the feature is kind of hidden and spread around the Typescript Handbook and if you turn to the internet to find out what you’re supposed to do with type definition files, there is still a lot of information on using TSD and Typings that drowns out the information about the new mechanism. I personally had this problem, crashing head first into Typescript, so I hope this post will help other developers better understand the history behind all of this.


TL;DR dude, just tell me which tool I need to use.

All you need in order to manage Typescript type definition files is NPM, but you need to be using Typescript 2.0 or higher. You will likely find information on the web about using Typings or TSD, but you can safely ignore it for a new project. For an ongoing project, it is also recommended by the Typescript team to move to this cleaner, simpler and officially supported mechanism.

npm install --save @types/lodash

The Typescript Handbook further explains how to use this friendly mechanism.

Jexia

Develop smart, not hard. Simplify the way you build applications. Use Jexia as your smart developer platform and create applications faster.

Thanks to Rishabh Jha

Mihai Coman

Written by

A software engineer by day and video gamer by night.

Jexia

Jexia

Develop smart, not hard. Simplify the way you build applications. Use Jexia as your smart developer platform and create applications faster.

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade