TypeScript 2.0 gives you more granular control over which built-in API declarations to include in your project. Previously, you were only able to access ES2015 APIs if your project was targeting ES6 . Now, the built-in standard library declarations have been modularized, and TypeScript allows you to pick and choose which type declarations to include.

The --lib Compiler Option

The type declarations for the JavaScript standard library have been partitioned into a bunch of API groups. At the time of writing in late November 2016, the following groups are defined:

dom

webworker

es5

es6 / es2015

/ es2015.core

es2015.collection

es2015.iterable

es2015.promise

es2015.proxy

es2015.reflect

es2015.generator

es2015.symbol

es2015.symbol.wellknown

es2016

es2016.array.include

es2017

es2017.object

es2017.sharedmemory

scripthost

You can pass any subset of the above groups to the TypeScript compiler via the --lib command line option or the lib property in your tsconfig.json. TypeScript will then only inject the typings you specified; that is, it will treat all other API groups as non-existent in your environment.

If you don't explicitly provide the lib option, TypeScript will implicitly inject a selection of API groups needed for web development. These are the defaults, depending on which language level your project targets:

["dom", "es5", "scripthost"] when targeting ES5

when targeting ES5 ["dom", "es6", "dom.iterable", "scripthost"] when targeting ES6

Using ES2015 Promises in a TypeScript Project Targeting ES5

Let's say you're working on a web project that targets ES5 so that it runs in all major browsers. Your tsconfig.json could look like this:

{ "compilerOptions": { "module": "commonjs", "target": "es5", "noImplicitAny": true, "strictNullChecks": true } }

Since the lib option is not specified, TypeScript will inject the API groups "dom" , "es5" , and "scripthost" by default. Now let's assume you want to use native ES2015 promises in your project. Those didn't exist in ES5, so you need to install a polyfill to make your code run in older browsers as well:

npm install --save es6-promise

You then import the polyfill in your application's entry module:

import "es6-promise"; // ...

With this polyfill in place, you can now use Promise in your application, and your code will run just fine. However, TypeScript will give you a compile-time error saying that it Cannot find the name 'Promise' . That's because the type declarations for Promise aren't included in any of the API groups injected:

You have to let TypeScript know that (because of your polyfill) Promise will exist at runtime. That's where the lib compiler option comes into play:

Note that you have to explicitly provide all API groups once you're overriding the default. The resulting tsconfig.json now looks like this:

{ "compilerOptions": { "module": "commonjs", "target": "es5", "noImplicitAny": true, "strictNullChecks": true, "lib": ["dom", "es5", "es2015.promise"] } }

And that's it! Now, the type checker is happy: