babel-preset-env + babel-polyfill documentation is misleading

[tkrotoff]

With Babel 6 (and 7) babel-preset-env and babel-polyfill documentations are misleading.

Based on my experimentations with babel-preset-env + babel-polyfill (for Babel 6) here: https://github.com/tkrotoff/babel-preset-env-example

Suggestions to improve babel-preset-env documentation:

• Clearly state that babel-preset-env is not enough alone, you also need babel-polyfill (or manually include the polyfills you want)
• Do not give examples with last 2 versions: not a good practice

Suggestions to improve babel-polyfill documentation:

• Clearly state here that import 'babel-polyfill' is the preferred way because useBuiltIns: true won't work otherwise
• Clearly state here that it's import 'babel-polyfill' OR webpack entry: ['babel-polyfill', './App.js'], not both

Also it should say somewhere there is nothing magic, Babel does not analyse the code to determine the needed polyfills :) i.e it will include Object.assign polyfill even if you don't use Object.assign inside your code: everything is based on targets.

[existentialism]

Also it should say somewhere there is nothing magic, Babel does not analyse the code to determine the needed polyfills

WRT to the 7 docs, this is not true as useBuiltIns: usage does attempt to only include polyfills which are used.

[existentialism]

Clearly state that babel-preset-env is not enough alone, you also need babel-polyfill (or manually include the polyfills you want)

I've been working on a preset-env docs overhaul that's long overdue, but happy to review a PR that improves this language.

I think @hzoo's original thinking was to only include babel-polyfill install info near the useBuiltIns option, since not everyone would be using it.

https://babeljs.io/docs/plugins/preset-env#usebuiltins

Do not give examples with last 2 versions: not a good practice

Was already discussed in https://github.com/babel/babel/issues/7789 (and https://github.com/babel/babel/pull/7790).

Clearly state here that import 'babel-polyfill' is the preferred way because useBuiltIns: true won't work otherwise Clearly state here that it's import 'babel-polyfill' OR webpack entry: ['babel-polyfill', './App.js'], not both

Good suggestions, would you like to send a PR?

[JonathanDn]

@tkrotoff Is there an update on this issue's status? I am experiencing difficulties similar to what you described. For example the usage of String .includes is no tr transpiled by Babel with preset-env in IE10/11 and causes an error. And babel-polyfill documentation seems broken as well... What polyfill should I add?

[JPustkuchen]

Same problem here. Would be nice to have that combination documented!