babel / babel/website

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

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

Description

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.

Contributor guide

No contributing guide indexed for this repository

Research direction

Start with the @babel/preset-env documentation, especially the Browserslist integration and useBuiltIns sections linked in the issue. Clarify early that target-based transforms do not by themselves provide polyfills, and explain when users should review the "usage" or "entry" options. Done means newcomers can understand the polyfill prerequisite and choose the relevant option.

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
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.