181

I have an existing project that has this line in tsconfig.json:

lib:["2016", "DOM"]

What is the purpose of this?

The only info I could find is this:

Specify library file to be included in the compilation. Requires TypeScript version 2.0 or later.

What does that mean?

Louis
  • 146,715
  • 28
  • 274
  • 320
Greg Gum
  • 33,478
  • 39
  • 162
  • 233
  • 2
    Does this answer your question? [What does the TypeScript "lib" option really do?](https://stackoverflow.com/questions/50986494/what-does-the-typescript-lib-option-really-do) – Evandro Coan Jun 23 '20 at 19:53

1 Answers1

95

This is a new typescript 2 feature and so it still lacks documentation, but you can read about it in the What's new in Typescript 2.0:

with --lib you can specify a list of built-in API declaration groups that you can chose to include in your project. For instance, if you expect your runtime to have support for Map, Set and Promise (e.g. most evergreen browsers today), just include --lib es2015.collection,es2015.promise. Similarly you can exclude declarations you do not want to include in your project, e.g. DOM if you are working on a node project using --lib es5,es6.

There's also a list of the API groups that are supported and a very short example in that link.

Nitzan Tomer
  • 155,636
  • 47
  • 315
  • 299
  • thanks, can you provide a simple example of _built-in API declaration groups_? Is it a library of polyfills? – Max Koretskyi Jan 20 '17 at 09:19
  • I'm not sure what you mean, your question has an example, also in the link I provided they have an example: `"lib": ["es5", "es2015.promise"]`. Another one is to target `es5` but to use `es6` features: `"lib": ["es6", "dom"]` – Nitzan Tomer Jan 20 '17 at 15:17
  • 31
    I meant that when I specify "lib": ["es5"], does it simply mean that I can use `es5` types in `ts` complaining of compiler, or some kind of poly-fills will be provided by `tsc`? – Max Koretskyi Jan 20 '17 at 15:21
  • 10
    The different libs can be found here: https://github.com/Microsoft/TypeScript/tree/master/lib They are definition files which the compiler uses – Nitzan Tomer Jan 20 '17 at 15:27
  • 6
    I see, thanks, so this basically means, that if I specify `"lib": ["es5"]` and don't specify "dom", `tsc` will complain about usage of DOM specific methods, correct? – Max Koretskyi Jan 20 '17 at 15:41
  • 16
    Beware that including "es2015.promise" or whatsoever doesn't include a polyfill into your compiled code. Instead you just notify the compiler that your code is using promises and it should be okay with that. If you need to add promises polyfills, consider either importing the polyfill in your code or using babel with corresponding machinery (babel-preset-env) as a post-step (or next loader in webpack) – Dmitrii Sorin Jul 26 '18 at 21:58
  • 58
    These groups make a promise to the compiler, "please don't complain about these APIs, I promise the browser will support them." E.g. If you add `es6` and _don't include polyfills_, old browsers will choke. – Steve Clay Aug 03 '18 at 13:18
  • 6
    @SteveClay your explanation is so easy, it's like I would be 5 years old and I would certainly understand it! Thanks! – Marecky Sep 11 '19 at 11:05