babel / babel/website

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

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

Description

With Babel 6 (and 7) [babel-preset-env](https://babeljs.io/docs/plugins/preset-env) and [babel-polyfill](https://babeljs.io/docs/usage/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](https://babeljs.io/docs/usage/polyfill/#usage-in-node--browserify--webpack) that `import 'babel-polyfill'` is the preferred way because `useBuiltIns: true` won't work otherwise
- Clearly state [here](https://babeljs.io/docs/usage/polyfill/#usage-in-node--browserify--webpack) 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`.

Contributor guide

No contributing guide indexed for this repository

Research direction

Start with the linked babel-preset-env and babel-polyfill documentation pages and compare their guidance with the linked babel-preset-env example. Update the pages to explain polyfill requirements, the preferred import or webpack entry usage, and target-based rather than code-analysis behavior; done means these recommendations are clear and consistent.

Written by the indexing model from the issue text.

Assessment

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.