search

babel / website

:globe_with_meridians: The Babel documentation website
https://babeljs.io/docs/en/index.html
MIT License
746 stars 1.3k forks source link

The section in the docs on Polyfills is unclear #2857

Open Richardinho opened 5 months ago

Richardinho commented 5 months ago

IMHO, the section on Polyfills in the documentation - https://babeljs.io/docs/usage - is not very clear. The section starts off saying:

As of Babel 7.4.0, this package has been deprecated in favor of directly including core-js/stable (to polyfill ECMAScript features):

Firstly, the deprecated package itself is not stated, which is a bit confusing (although I assume it's @babel/polyfill).

Secondly, it's not clear whether or not we're supposed to ignore this section entirely because of the deprecation warning. The fact that the section later includes instructions on how to install @babel/polyfill makes me think that these are old instructions and so we should ignore them, but I'm not sure because it also includes instructions for using core-js.

After these instructions we have:

Then import core-js (to polyfill ECMAScript features) first, in our entry file to emulate a full ES2015+ environment since @babel/polyfill has been deprecated:

So what is this saying? all we need to do is import core-js and all the previous instructions are irrelevant? Or we need to follow the preceding instructions and install core-js?

Then further down the page, in the summary, it mentions @babel/polyfill again as if it's not deprecated!

It seems to me that this section should be split up into two sections:

  1. How to use @babel/polyfill if you really want to, with the caveat that it's deprecated
  2. How to use core-js

Or perhaps just say that @babel/polyfill is deprecated and only have the second section.

babel-bot commented 5 months ago

Hey @Richardinho! 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.