The process of coding Type Definitions is straight forward. However while developing Type Definitions, it’s useful to see them in action in a real project, so uncertainty about how the
.d.ts file would eventually be distributed proved to be a sticking point when writing and testing Type Definitions for the first time.
A TypeScript primer
Let’s begin with a quick primer on the language and highlight why Type Definitions are of interest.
The main features of TypeScript:
- It is an Object Oriented Programming language
- It provides for optional type hints (which we’ll focus on in this post)
Type Definitions are the concept behind some of the most desirable benefits of TypeScript. They define the “shape” and types associated with a library’s API. They enable developers to add type hints to their code base and these are checked at compilation time which helps avoid bugs. They also facilitate advanced IDE features like “code completion” which can improve the developer experience and speed up development.
Options for distributing Type Definitions
Before we go too far, it’s important to note that there are a few ways that developers can create and distribute the Type Declaration File (identifiable by the
Developers and contributors of TypeScript projects
It should be no surprise that for projects written in TypeScript, it is exceptionally easy to generate Type Definitions. It is simply a matter of including the
--declaration and/or related
tsc TypeScript compiler options. From there the generated Type Definitions can be inspected and refined manually to ensure they match the developer’s intent.
From there it is simply a matter of including the generated
There are two main ways you can publish your declaration files to npm:
- bundling with your npm package, or
- publishing to the @types organization on npm.
If you control the npm package you are publishing declarations for, then the first approach is favored.
This bundling is convenient because the source and Type Definition is available in one place and are versioned together as part of one package.
Everyone without the ability to commit or raise PRs and publish package versions
The main downside to this approach is a side-effect of physically separating code that is otherwise closely related. It leaves the potential for version mismatches and also introduces lead-time associated with submitting Pull Requests through the DefinitelyTyped project repository.
Still, it’s considerably better than no Type Definitions at all.
Coding the Type Definitions
- dtslint: a utility built on TSLint for linting TypeScript declaration (.d.ts) files [dtslint on Github]
- dts-gen: creates starter TypeScript definition files for any module or library [dts-gen on Github]
In addition, the project’s
package.json now declares the
"types" property. This allows the TypeScript compiler and IDEs with TypeScript support to locate the Type Declaration file and apply the Type Definitions it contains.
The end result
To see it in action in a demo project, take a look at the Stream Angular Example project on Github.