babel / babel/website

The section in the docs on Polyfills is unclear

Open
#2,857 1 comment 3 reactions 0 assignees View on GitHub
Dominant language
TypeScript
Stars
777
Forks
1.4k
Avg merge
16h 45m
Merged PRs (30d)
3

Description

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](https://github.com/zloirock/core-js) (to polyfill ECMAScript features) first, in our entry file to emulate a full ES2015+ environment since [@babel/polyfill](https://babeljs.io/docs/babel-polyfill) has been [deprecated](https://babeljs.io/docs/usage#polyfill-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.

Contributor guide

No contributing guide indexed for this repository

Research direction

Open the Polyfills section at https://babeljs.io/docs/usage and compare its deprecation notice, installation instructions, and summary. Clarify whether @babel/polyfill should be used, distinguish it from core-js guidance, and ensure the final section consistently explains the recommended path.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript
Domain
documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Stale
Clarity
Clearly specified
Newbie friendliness
52/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.