Get Your TypeScript Definitions from NPM

Get Your TypeScript Definitions from npm

Derived from photo by, CC-BY

If you use TypeScript, you appreciate what the type system provides with IntelliSense and easier refactoring. This experience is quite seemless with code you have written. However, using third-party libraries has left many struggling with complex configurations.

With the advent of ECMAScript 2015 (ES2015) modules and the rise of npm as the defacto JavaScript package manager, configuring your type definitions has gotten more complicated. Not only did you have to ensure that your import statements resolved to the correct scripts but now also the correct type definitions.

Thankfully, the community is standardizing third-party type resolution similar to how it is standardizing on ES2015 modules and npm.

Once Upon a Time

Back in the early days of TypeScript, you used to reference type definitions at the top of the .ts file like this:

/// <reference path="../lib/my-favorite-library.d.ts" />

Also you probably got the type definitions from a dedicated registry somewhere like DefinitelyTyped and maybe even used command line tools to setup and configure these type definitions like tsd or typings.

There were shortcuts and optimizations but ultimately it was a whole other set of configuration and package management to get third party libraries compiling with TypeScript.

Relative Path Module Resolution

While you can still write your comment-based type references, the industry has adopted the ES2015 module standard and so has TypeScript.

By adopting this standard, each JavaScript (or TypeScript) file essentially represents a module with its own scope. Any dependencies that this module requires are imported directly from another module by the module's URL. In the future, browsers will understand how to parse this syntax and load each module as needed from the server. Today, TypeScript transpiles these import statements into a configurable module loader syntax such as AMD, UMD, or CommonJS.

Take for example the fact that your GrooveService takes a dependency on your FunkService. Because you wrote your FunkService in TypeScript, both the scripts and the types are found at the same location.

import { FunkService } from './funk-service';

On the other hand, what if you are using angular in Angular 1.x? Initially, you might think to reference it by relative path:

import * as angular from './node_modules/angular/index.js';

This makes sense because this location is where the scripts reside and the browser will load the correct library. However, TypeScript complains that it can't find angular. Well, it turns out the angular library doesn't include TypeScript definitions in the package. TypeScript tried to find the type definitions at the relative path, but they weren't there and you got the dreaded red squiggle..

Angular IntelliSense Squiggle

Traditionally, this is where tsd or typings came into the picture. These repositories contained packaged type defintions for many popular libraries independent of the library provider. And while these repositories solved a real problem in obtaining type definitions, they weren't easy to setup and configure. After all, who wants to maintain two sets of packages managed by two different tools with two different configurations just for the ability to reference one library using TypeScript?

There's another problem with taking a relative path reference to an npm module, what if your code is distributed as an npm package? If you have spent time reading up on npm dependency resolution, you know that you can't guarantee the location of your dependencies in npm. They may be dropped at different levels of the folder structure and therefore attempts to reference npm modules by relative path are fragile.

Node Module Resolution

In order to solve the npm module resolution problem, the folks at TypeScript decided to just follow the npm model. This solution makes it seamless to reference both the code and the types using the same syntax used in NodeJS.

import * as angular from 'angular';

Given this import statement, NodeJS understands that angular is equivalent to /node_modules/**/angular/index.js. It doesn't know exactly which directory it will be in but it knows how to find it.

As of TypeScript 1.6, the compiler understands how to look for type definitions in the same fashion. TypeScript looks for something roughly equivalent to /node_modules/**/angular/index.d.ts. This is great because it ensures that the code and the types can be found in the same npm package.

But what if the code and the types aren't in the same package? For instance, the Angular 2 libraries ship with type definitions included in the package but Angular 1.x does not. This introduces another great solution from the community. Instead of using tsd or typings for your third-party type defintions, now you can just use npm.

The @types organization is available on the public npm registry for the purpose of hosting third-party type definitions that don't ship with their repective package. So if there is a set of types available independent of the package's publisher, by convention you can find them on npm using @types/package-name. For example to download types for angular, you get them by installing the @types/angular npm package. Furthermore, TypeScript understands how to resolve types from the @types directory out of the box.

To ensure node module resolution for your project, set it in your tsconfig.json file:

    "compilerOptions": {        
        "moduleResolution": "node"

Note: To read more about how TypeScript handles node module resolution, there are more details in the TypeScript documentation.

Bringing Node Module Resolution to the Browser

This all sounds great – less tooling dependencies, easier configuration. NodeJS runs everywhere – desktop clients, web servers, Linux, MacOS, Windows. But unfortunately, when the web browser tries to load scripts from angular you get a 404 result. The browser doesn't understand how to convert the npm package name into the URL for which the script resides.

This is the place where the node module abstraction breaks down. But think about it for a second. Yes, NodeJS doesn't run in the browser. Yes, you aren't necessarily writing a NodeJS backend. But what NodeJS has done is unify the runtime on which web developers run their client-side tooling. This is the environment on which you do your TypeScript compilation, combining modules, minifying – basically optimizing your code to be consumed by the browser. And so it still makes sense that npm would be the best solution for module resolution of both the scripts and the types.

There are a ton of different ways to prepare your application's npm modules for delivery to the browser and you can bet that there will be more coming in the future. For now, SystemJS is a good place to start. Many deveopers already use this library as a script loader and by adding some additional configuration, it's possible to map npm-based dependencies to a relative URL.

Without any additional configuration, the browser is going to see the import statment for angular and attempt to request /angular from the server. What should really happen is that the browser requests the code from the actual package folder like node_modules/angular/index.js. So using your SystemJS configuration file, add the following:

    packages: {
        '': {
            defaultExtension: 'js',
            map: {
                'angular': './node_modules/angular/index.js'

This code configures the root of your application (at the path '') to always add a .js extension if one is not present and to also map the 'angular' path. Now when SystemJS sees the import statement for 'angular', it maps that to a request for node_modules/angular/index.js as defined in the configuration.

Automatic Typings Acquisition

If you've made it this far, you understand how this simplifies the process of acquiring and referencing type definitions. It's become simple enough in fact that the Visual Studio Code team is working to make it automatic in the editor. As of this writing, the feature is released but the team admits it still has rough edges. Even still, you can read more about it in the release notes and start trying it by downloading version 1.7.2 or later.

Keep in mind, the tooling may have drawbacks even when it is complete and it's helpful to know what the tooling is doing underneath the covers. Also, this tooling doesn't address the need for mapping npm package names to URLs in the browser like discussed with SystemJS.

The End

The point here is that node module resolution has become the defacto standard in the web development community and TypeScript is no exception. Now that @types is available on npm, you have one place to get your third-party libraries and type definitions – npm.

The tricky party is still configuring node module resolution for the browser but you see how it's possible to setup SystemJS to handle the mapping. Look for more tooling discussion in future posts.

Are you using ES2015 modules and node module resolution with TypeScript? What is your preferred method of mapping the module names to URLs for the browser?

Leave a Reply

Your email address will not be published. Required fields are marked *