What are typescript `--lib` library files?

Question

There is a similar question. That covers what typescript does with the option. The below question and answer covers where the lib files come from at runtime.

When I looked up the description for the --lib compiler option it says:

List of library files to be included in the compilation.

What are these library files and how are they included? The repository I'm studying has the following settings?

"compilerOptions": {
  "target": "es5",
  "module": "es2015",
  "lib": ["es2015", "dom"]
},

How would the output be different if --lib were not set to ["es2015", "dom"]?

Answer 1

They tell the typescript compiler that those type libraries are available during the run-time and it won't complain that your target es version is missing features.

Your config is targeting es5, but you're telling typescript that "es2015" features will be available - so for example Promise and Map. Similarly you have "dom", so typescript knows that you have window and browser-dom features.

As far as I'm aware, it won't alter the output... typescript will simply error when you try to use features that are not present in your target es version.

You'd do this when you want to target old browsers, but also want to use, for example, Promises. So we tell the compiler its available with lib:["es2015.promise"] then you run something like core-js or bluebird at execution-time to polyfill the Promise functionality.