What does the TypeScript “lib” option really do?

Question

I have still not been able to find good answer for this. The "target" option defines, what version of Javascript the result will run on. The "lib" option is less clearly described anywhere. Seems like it is a more granular way to describe the target environment, but then it seems strange it affects what you can write in the .ts source files. Thought TS what as superset of JS, so why does it affect whether, e.g., Promise() is available or not? This seems like it does not only define the target but also affect what functions you have available in Typescript. Can someone explain that clearly or direct to an answer (there is none at typescriptlang.org or in the books I have looked at, e.g., "Specify library files to be included in the compilation", which explains absolutely nothing.

Answer 1

Typescript does not have any built-in types all types come from a set of base definitions (located in the lib folder in the typescript install directory). By default the target defines which libs are included. For example the docs state:

Note: If --lib is not specified a default list of librares are injected. The default libraries injected are:

► For --target ES5: DOM,ES5,ScriptHost

► For --target ES6: DOM,ES6,DOM.Iterable,ScriptHost

The basic idea is that while target is deals with language features (more specifically which language features need to be down compiled, ex: for-of, or arrow functions), the lib option deals with what facilities the runtime environment has (ie. what built-in objects look like, what they are).

Ideally the default libs for a given target should be used. We may, however, have an environment which supports some of the runtime facilities but not the language features, or we may target runtime with a lower es version and poly-fill some of the runtime facilities, which can be in general done for some things (ex: Promises).

Answer 2

Remember, TS never injects polyfills in your code. It's not its goal. Complementing the answer above:

target tells TS which ES specification you want the final code to support. If you configure it as ES5, TS will down compile the syntactic features to ES5, so any arrow functions (() => {}) in the code will be transformed to functions. But it's also going to assume your browser supports all ES5 functional features at runtime. For example, if you have Array.isArray (an ES5 feature) in your code and you try to open your website in IE8, it's going to break because it does not support this. You have to polyfill it if you want to support that browser.

lib tells TS what type definitions to include in your project. If you have "target": "es5", the default value for lib will be ["dom", "es5", "ScriptHost"]. It means what functional features the browser will support at runtime. If you add any polyfills for things above your target, is here where you configure this extra support.

Example: You need to support IE11 and you have Promise in your code. IE11 does not support promises, so you have to import yourself a polyfill in your code, and then tell TS:

"target": "es5",
"lib": ["es5", "dom", "ScriptHost", "es2015.promise"]