@babel/preset-env not explicit about the need for Polyfills

[thernstig]

Reading https://babeljs.io/docs/en/babel-preset-env

For example https://babeljs.io/docs/en/babel-preset-env#browserslist-integration has an example where "useBuiltIns": "entry" is used. This will however only work if a user has added polyfills already. For many (most) new projects I would suspect users to not have manually added polyfills. Would the useBuiltIns: "usage"' (https://babeljs.io/docs/en/babel-preset-env#usebuiltins) then be more natural for users to use? Because the text says this, it is not entirely true this will work for many projects:

For example, to only include polyfills and code transforms needed for users whose browsers have >0.25% market share (ignoring browsers without security updates like IE 10 and BlackBerry):

What I am missing early in the documentation is the fact that useBuiltIns is most often very important. Would it not make sense to have a paragraph about that "To handle polyfills you have two options. 1) You have not added them manually in the codebase, then take a look at useBuiltIns: 'usage'. 2) You already have polyfills manually added, then take a look at useBuiltIns: "entry".

In essence I feel the text is quite clear on that it does transforms early on, but for newcomers it is not clear that polyfills are needed. So in most new projects where you would want @babel/preset-env to automatically inject polyfills, that is not clear. And it is very important, otherwise your app will not work on the targets you specified in your browserslist config.

[babel-bot]

Hey @thernstig! We really appreciate you taking the time to report an issue. The collaborators
on this project attempt to help as many people as possible, but we're a limited number of volunteers,
so it's possible this won't be addressed swiftly.

If you need any help, or just have general Babel or JavaScript questions, we have a vibrant Slack
community that typically always has someone willing to help. You can sign-up here
for an invite.

[thernstig]

Obvious answer to this question probably, but being explicit here: NOT having polyfills (via e.g. useBuiltIns: 'usage') would basically mean the entire chain of setup with @babel/preset-env be moot. Because you are then not polyfilling features for the browsers you target. So the transforms done is good, but it does not take you all the way to support the browsers you say you do. Correct?

That is why I feel this is so important so users understand that option is important.