Clarification on functionality of Typescript's target and lib settings

Question

When tsconfig.json has the following

"target": "es5",
"lib": [ "es6", "dom", "es2017" ]

it doesn't seem to convert es2017 constructs to es5. For instance, the following will fail on IE11:

var foo = [1, 2, 3].includes(1);

Is this by design or am I missing a setting in tsconfig.json?

Answer 1

Clarification on functionality of Typescript's target and lib settings

The simplified way I think about it is that target says what syntax the output JavaScript will have, and lib says what API members your TypeScript source code can use. There is more detail in the answers to these two questions:

• Typescript- What is target in tsconfig?
• What does the tsconfig option "lib" do?

...it doesn't seem to convert es2017 constructs to es5... Is this by design or am I missing a setting in tsconfig.json?

You're right. This is by design. TypeScript transpiles to the target syntax; it does not polyfill the API members that are missing from the target. Here is a quote from a core member of the TypeScript team:

I think you're confusing transpilation with auto-polyfilling. TypeScript doesn't automatically polyfill for you like Babel does, but does perform syntactic downleveling (e.g. for arrow functions). If you want to use ES6 runtime prototype methods, I'd simply include an appropriate ES6 polyfill and its accompanying definition file.

If your lib includes API members (such as Array.prototype.include) that aren't present in the target runtime, then you need to install polyfills that provide those API members.