babel-preset-env + babel-polyfill documentation is misleading
- 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