Typings

The type definition manager for TypeScript.

Quick Start

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

# Search for definitions.
typings search tape

# Find ambient typings (includes DefinitelyTyped).
typings search react --ambient

# Install ambient typings (and persist selection in `typings.json`).
typings install react --ambient --save

# Use `main.d.ts` (in `tsconfig.json` or as a `///` reference).
cat typings/main.d.ts

Important: For existing TSD users, Typings will install from DefinitelyTyped using the --ambient flag. Regular dependencies are maintained in the registry.

Features

• Package manager parity
  • Familiar commands like init, install, rm and ls
• Installation from GitHub, BitBucket, NPM dependencies, Bower dependencies and HTTP(s)
  • If a project uses Typings, you can install it locally - try typings install npm:popsicle
• Simple typings configuration file
  • Persist dependencies in typings.json and everyone on the project can replicate it
• Name-spaced dependencies (not for ambient dependencies - those are always global)
  • TypeScript definitions will be name-spaced and contained from leaky type information

Usage

Typings is the simple way to manage and install TypeScript definitions. It uses typings.json, which can resolve to GitHub, NPM, Bower, HTTP and local files. Packages can use type definitions from various sources and different versions, and know they will never cause a conflict for users.

typings install debug --save

A public registry is maintained by the community, and is used to resolve official type definitions for JavaScript packages.

Init

typings init

Options: [--upgrade]

Initialize a new typings.json file. If you're currently using TSD, you can use --upgrade to convert tsd.json to typings.json.

Install

typings install # (with no arguments, in package directory)
typings install <pkg>[@<version>] [ --source [npm | github | bower | ambient | common] ]
typings install file:<path>
typings install github:<github username>/<github project>[/<path>][#<commit>]
typings install bitbucket:<bitbucket username>/<bitbucket project>[/<path>][#<commit>]
typings install <http:// url>

Write a dependency to the typings/ directory, optionally persisting it in typings.json.

Flags

• --save, -S Save as a dependency in typings.json
• --save-dev, -D Save as a dev dependency in typings.json
• --ambient, -A Write as an ambient dependency (use with --save and --save-dev)
• --name, -n The name of the dependency (required for non-registry dependencies)

Possible Locations

• http://<domain>/<path>
• file:<path>
• github:<org>/<repo>/<path>#<commit>
• bitbucket:<org>/<repo>/<path>#<commit>
• npm:<package>/<path>
• bower:<package>/<path>

Where path can be to typings.json, a .d.ts file, or empty. When the path is empty, or not a .d.ts file, typings.json will be appended to the path.

Please note: npm and bower resolve using their respective algorithms over the local filesystem. They will need to be installed before running typings install. The other schemes (http, https, github, bitbucket) resolve over HTTP(s). Finally, file is a location in the local filesystem relative to the typings.json directory.

Registry

Installations without a specific location will looked up the registry using the Typings API. For example, typings install debug will resolve to this data. Anyone can contribute typings to the registry, just make a pull request.

Example

Install node typings:

typings install node --save --ambient

The name is persisted in typings.json. The --save flag is used to write to typings.json, which you can use to re-install your typings later. The --ambient flag is used to confirm that this dependency is ambient.

Uninstall

typings uninstall <pkg> [--ambient] [--save | --save-dev]

Remove a dependency from the typings/ directory, and optionally remove from typings.json.

Flags

• --save, -S Remove from dependencies in typings.json
• --save-dev, -D Remove from dev dependencies in typings.json
• --ambient, -A Remove as an ambient dependency (use with --save and --save-dev)

List

typings ls [--ambient]

Print the typings dependency tree. This command resolves on demand and is not currently cached.

Search

typings search [query] [--ambient]

Options: [--name] [--source] [--offset] [--limit]

Search the registry for available typings.

Bundle

typings bundle --name [string]

Options: [--browser] [--out] [--source]

Bundle the current project types into an single ambient module.

FAQ

Why?

• Typings makes external modules, not ambient modules, first class (E.g. no declare module "x" in dependencies)
  • A lot of ambient module declarations suffer from exposing implementation details incorrectly
  • External module declarations are emitted by TypeScript already, and used with the moduleResolution option
  • You can immediately contribute typings back to the author!
• Typings cleanly represents the module structure
  • Supporting the browser field (used by Webpack, Browserify, etc.) can produce different types
  • Need type definitions for each file? Done. Some modules promote requiring into the dependencies for "add-ons"
• TypeScript modules should be publish-able to any package manager
  • Ambient modules can not be published to a package manager
  • Publishing ambient modules to a package manager cripples your users that run into duplicate identifiers
• Typings are decentralized
  • Write and install your own type definitions without friction
  • Author can maintain type definitions in isolation from other typings (using separate GitHub repos, for example)

Configuration

Typings supports configuration using rc. The config options can be set using CLI arguments, environment variables prefixed with typings_ or a .typingsrc file.

• proxy A HTTP(s) proxy URI for outgoing requests
• rejectUnauthorized Reject invalid SSL certificates (default: true)
• ca A string or array of strings of trusted certificates in PEM format
• key Private key to use for SSL (default: null)
• cert Public x509 certificate to use (default: null)
• userAgent Set the User-Agent for HTTP requests (default: typings/{typingsVersion} node/{nodeVersion} {platform} {arch})

main.d.ts And browser.d.ts

To simplify integration with TypeScript, two files - typings/main.d.ts and typings/browser.d.ts - are generated which reference all the typings installed in the project. To use this, you can add the reference to tsconfig.json files:

{
  "files": [
    "typings/main.d.ts"
  ]
}

Or as a reference to the top of TypeScript files:

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

If you're building a front-end package it's recommended you use typings/browser.d.ts instead. The browser typings are compiled by following the browser field overrides.

Please note: If you're relying on "exclude" behavior instead, you can exclude typings/browser.d.ts and typings/browser (replace browser with main, if you desire).

References

During installation, any references (E.g. /// <reference path="..." />) are stripped. There is no simple way to include the contents from the other file within the project. With legacy projects, these references can denote dependencies or ambient dependencies, so can't be relied on in any formal way. Installation will print the references that were stripped during installation, and you can continue installation of dependencies yourself.

How Do I Use Typings With Git and Continuous Integration?

If you're already publishing your module with TypeScript, you might be using NPM scripts to automate the build. To integrate Typings into this flow, I recommend you run it as part of the prepublish or build steps. For example:

{
  "scripts": {
    "build": "rm -rf dist && tsc",
    "prepublish": "typings install && npm run build"
  }
}

If you're using some other set up, just run typings install before you execute the build step. This will install the type definitions from typings.json before the TypeScript compiler runs.

How Do I Write Typings Definitions?

Writing a new type definition is as simple as creating a new package. Start by creating a new typings.json file, then add dependencies as normal. When you publish to GitHub, locally, alongside your package (NPM or Bower) or even to your own website, someone else can reference it and use it.

{
  "name": "typings",
  "main": "path/to/definition.d.ts",
  "author": "Blake Embrey <[email protected]>",
  "description": "The TypeScript definition dependency manager",
  "dependencies": {}
}

• main The entry point to the definition (canonical to "main" in NPM's package.json)
• browser A string or map of paths to override when resolving (canonical to "browser" in NPM's package.json)
• ambient Denote that this definition must be installed as ambient
• name The name of this definition
• dependencies A map of dependencies that need installing
• devDependencies A map of development dependencies that need installing
• ambientDependencies A map of environment dependencies that may need installing
• ambientDevDependencies A map of environment dev dependencies that may need installing

What Are Ambient Dependencies?

Ambient dependencies are type definitions that provide information about the environment. Some examples of "environment" dependencies are Node.js, Browserify, window and even Array.prototype.map. These are globals that already exist, you do not "require" them. If your package exposes a module and/or ambient dependencies, it's recommended you expose a way to install the ambient definitions (explain installation in the docs, for instance).

Should I Use The typings Field In package.json?

Maybe. If you're relying on typings to provide type dependencies, I recommend that you omit the typings entry for now. If you don't use the typings.json file, add typings in package.json. This is because TypeScript 1.6+ comes with node module resolution built-in, but unless all the packages in the NPM dependency tree have their own typings entry inline you'll be breaking TypeScript users of your library. Typings has complete support for the node module resolution strategy used in TypeScript.

Where do the type definitions install?

Typings are compiled and written into the typings/ directory alongside typings.json. The structure looks like this:

typings/{main,browser}/{ambient,definitions}/<dependency>/<dependency>.d.ts
typings/{main,browser}.d.ts

Where typings/{main,browser}.d.ts is a collection of references to installed definitions. Main and browser typings are written to separate directories for tsconfig.json exclude support - you can completely exclude both the main or browser typings.

Contributing

The scripts to build the project are in package.json. Use npm run test and npm run build. For initial compilation, you will need to install the typings in typings.json. Yes, recursive dependencies. Use npm install -g typings and run typings install before building, or look at npm run bootstrap to see how Typings bootstraps itself.

License

MIT