Typescript Libraries

TL;DR: With Typescript if you’re using “target”: “es2016” then LIB is not needed, but if you’re using “target”: “es5”, then you need “lib”: [“es6”] in tsconfig for Promise etc. to work, coz Note: If --lib is not specified a default library is injected. The default library injected is:
► For --target ES5: DOM,ES5,ScriptHost
► For --target ES6: DOM,ES6,DOM.Iterable,ScriptHost

ref: https://basarat.gitbooks.io/typescript/content/docs/types/lib.d.ts.html

SAMPLE CODE: https://github.com/tkhemani/TSCode/commit/e564cc73b4fb92de8e6bc0ef074ad837cdf31adb

A special declaration file lib.d.ts ships with every installation of TypeScript. This file contains the ambient declarations for various common JavaScript constructs present in JavaScript runtimes and the DOM.

  • This file is automatically included in the compilation context of a TypeScript project.
  • The objective of this file to make it easy for you start writing type checked JavaScript code.

You can exclude this file from the compilation context by specifying the --noLib compiler command line flag (or "noLib" : true in tsconfig.json).

lib.d.ts inside look

The contents of lib.d.ts are primarily a bunch of variable declarations e.g. window, document, mathand a bunch of similar interface declarations e.g. Window , Document, Math.

Compiler target effect on lib.d.ts

Setting the compiler target to be es6 causes the lib.d.ts to include additional ambient declarations for more modern (es6) stuff like Promise. This magical effect of the compiler target changing the ambience of the code is desirable for some people and for others its problematic as it conflates code generation with code ambience.

However if you want finer grained control of your environment you should use the --lib option which we discuss next.

lib Option

Sometimes (many times) you want to decouple the relationship between the compile target (the generates JavaScript version) and the ambient library support. A common example is Promise, e.g today (in June 2016) you most likely want to --target es5 but still use latest stuff like Promise. To support this you can take explicit control of lib using the lib compiler option.

Note: using --lib decouples any lib magic from --target giving you better control.

You can provide this option on the command line or in tsconfig.json (recommended):

Command line:

tsc --target es5 --lib dom,es6


"compilerOptions": {
    "lib": ["dom", "es6"]

The libs can be categorized into categories:

  • JavaScript Bulk Feature:
    • es5
    • es6
    • es2015
    • es7
    • es2016
    • es2017
  • Runtime Environment
    • dom
    • webworker
    • scripthost
  • ESNext By-feature options (even smaller than bulk feature)
    • es2015.core
    • es2015.collection
    • es2015.generator
    • es2015.iterable
    • es2015.promise
    • es2015.proxy
    • es2015.reflect
    • es2015.symbol
    • es2015.symbol.wellknown
    • es2016.array.include
    • es2017.object
    • es2017.sharedmemory

NOTE: the --lib option provides extremely fine tuned control. So you most likey want to pick an item from the bulk + enviroment categories.

My Personal Recommentation:

"compilerOptions": {
    "target": "es5",
    "lib": ["es6", "dom"]


BEST: Use the target and lib compiler options to compile directly to es5 without needing to install the es6-shim. (Tested with TypeScript 2.1.4).

// tsconfig.json
    "compilerOptions": {
        "target": "es5",
        "lib": [
    "include": [
    "exclude": [

Alternative #2

Use NPM to install the es6-shim from the types organization.

npm install @types/es6-shim --save-dev

Alternative #3

Before TypeScript 2.0, use typings to install the es6-shim globally from DefinitelyTyped.

npm install typings --global --save-dev
typings install dt~es6-shim --global --save-dev

The typings option uses npm to install typings globally and then uses typings to install the shim. The dt~ prefix means to download the shim from DefinitelyTyped. The --global option means that the shim’s types will be available throughout the project.


ref: http://stackoverflow.com/questions/27573365/how-to-use-typescript-with-native-es6-promises


Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s