@babel/preset-env: Clarify `useBuiltIns` usage and purpose #2067

bowernite · 2019-07-19T14:06:49Z

This PR clarifies what useBuiltIns is for, and how to use it, better (IMO 🙂).

Specifically, I really struggled using this option in one of my projects. It took me a long time to understand:

That this option only told Babel how to import polyfills, and that it didn't come with them
- Specifically, that you had to npm install them yourself
core-js and regenerator/regenerator-runtime were exactly the two polyfills it supported
- The old documentation focuses on core-js, and brushes over regenerator
regenerator-runtime/runtime was installed via the regenerator npm package
- Just took me a while to figure which exact package to install (regenerator-runtime? Just regenerator?)

Feedback welcome 😃

netlify · 2019-07-19T14:10:30Z

Deploy preview for babel failed.

Built with commit 6f82595

https://app.netlify.com/sites/babel/deploys/5e6c15e822b418000b7f7649

nicolo-ribaudo · 2019-09-05T14:04:02Z

Could we also add a note that it is incompatible with transform-runtime? (ref: babel/babel#10271)

docs/preset-env.md

zloirock · 2019-09-05T14:09:53Z

docs/preset-env.md


-Since `@babel/polyfill` was deprecated in 7.4.0, we recommend directly adding `core-js` and setting the version via the [`corejs`](#corejs) option.


This note is useful for many users, so I don't think that remove it and add a stripped version is a good idea.

I have a line below that reads:

> NOTE: Previously, these would be installed via `@babel/polyfill`, which is now deprecated. The above method of installing these polyfill packages is the recommended way.

I don't see this as any more stripped down than the line you commented on, just moved down to be more contextual. Do you want me to move this line up?

zloirock · 2019-09-05T14:12:29Z

docs/preset-env.md


-npm install core-js@2 --save


Usage of different core-js versions causes many questions and problems for users, so remove the note of how to install different core-js versions is not a good idea.

That's what I was trying to do by removing the different versions. I found the fact that the documentation had two different versions of core-js confusing -- why are there two? Which one should I be using? It made me do unnecessary research into core-js, which I don't think a user of @babel/preset-env should have to do.

Are there specific use cases for 2 vs 3? If so, I'd be happy to add notes about them 🙂

patrick-mcdougle · 2019-09-26T23:12:00Z

Could we also add a note that it is incompatible with transform-runtime? (ref: babel/babel#10271)

@nicolo-ribaudo But if preset-env and transform-runtime don't work together, won't people lose the benefit of sharing the runtime/helper code across the entire project? Not sure people are going to like that.

nicolo-ribaudo · 2019-09-26T23:17:29Z

Sorry, I meant with transform-runtime's core-js option

bowernite · 2019-10-01T12:33:57Z

Could we also add a note that it is incompatible with transform-runtime? (ref: babel/babel#10271)

Do you have wording in mind on this? Might be easier than me trying to come up with something and having it be inaccurate 😅

docs/preset-env.md

nicolo-ribaudo · 2019-10-21T18:06:07Z

docs/preset-env.md


-Since `@babel/polyfill` was deprecated in 7.4.0, we recommend directly adding `core-js` and setting the version via the [`corejs`](#corejs) option.
+- `core-js`: For standard JS built-ins
+- `regenerator-runtime`: For generator and `async`/`await` support


Note that this isn't needed for async/await if your browser supports generators. (because async/await is transpiled to a generator)

Can you also mention this here?

Isn't that assumed for this whole section, since preset-env's entire purpose is to fill in for browsers' shortcomings.

i.e. core-js isn't needed if your browser supports all JS built-ins that it brings

My point was that regenerator-runtime isn't always needed by browsers that don't support async/await, while this sentence implies the opposite.

regenerator-runtime is only needed for browsers that don't support generators.

I see what you mean, but don't know exactly what text would make sense.

Do you have a suggestion?

Maybe this?

Suggested change

- `regenerator-runtime`: For generator and `async`/`await` support

- `regenerator-runtime`: For generators and `async`/`await` in browsers without generators support

Done. Changed up your suggestion a little. I don't think everyone knows that async/await is built on generators, so I just grouped them together so it would be clear for everyone

docs/preset-env.md

Co-Authored-By: Nicolò Ribaudo <nicolo.ribaudo@gmail.com>

existentialism

Let's get this landed, I just made a few small comments.

existentialism · 2020-03-10T14:16:04Z

docs/preset-env.md

 > Multiple imports or requires of those packages might cause global collisions and other issues that are hard to trace.
 > We recommend creating a single entry file that only contains the `import` statements.

-This option enables a new plugin that replaces the `import "core-js/stable";` and `import "regenerator-runtime/runtime"` statements (or `require("corejs")` and `require("regenerator-runtime/runtime")`) with individual requires to different `core-js` entry points based on environment.
+This option enables a new plugin that replaces the `import "core-js"` and `import "regenerator-runtime/runtime"` statements with only what's needed from each of them, depending on the target environments.


Suggested change

This option enables a new plugin that replaces the `import "core-js"` and `import "regenerator-runtime/runtime"` statements with only what's needed from each of them, depending on the target environments.

This option enables a plugin that replaces the `import "core-js"` and `import "regenerator-runtime/runtime"` statements with only what your target environments need from each of them.

existentialism · 2020-03-10T14:23:32Z

docs/preset-env.md

-npm install core-js@3 --save
-
-# or
+Since these packages do not come with Babel or `@babel/preset-env` itself, they'll need to be installed as production-level dependencies. This way, when the Babel-generated code imports them, they'll be accessible (in `node_modules`).


Wonder if we should be more explicit than "production-level", something like:

installed a dependencies (not devDependencies)

docs/preset-env.md

Co-Authored-By: Nicolò Ribaudo <nicolo.ribaudo@gmail.com>

preset-env: clarify useBuiltIns better

30b9e42

existentialism mentioned this pull request Jul 19, 2019

About how to useBuiltIns options for polyfill babel/babel#10239

Closed

nicolo-ribaudo added the docs label Sep 5, 2019

zloirock reviewed Sep 5, 2019

View reviewed changes

docs/preset-env.md Outdated Show resolved Hide resolved

zloirock reviewed Sep 5, 2019

View reviewed changes

vdh reviewed Oct 21, 2019

View reviewed changes

docs/preset-env.md Outdated Show resolved Hide resolved

bowernite added 2 commits October 21, 2019 10:58

don't call regenerator a polyfill

ba072a1

regenerator --> regenerator-runtime

66859b9

nicolo-ribaudo reviewed Oct 21, 2019

View reviewed changes

docs/preset-env.md Outdated Show resolved Hide resolved

bowernite and others added 2 commits November 4, 2019 19:32

Update docs/preset-env.md

1a48e50

Co-Authored-By: Nicolò Ribaudo <nicolo.ribaudo@gmail.com>

Update preset-env.md

42b5bb9

existentialism approved these changes Mar 10, 2020

View reviewed changes

nicolo-ribaudo reviewed Mar 10, 2020

View reviewed changes

docs/preset-env.md Outdated Show resolved Hide resolved

Update docs/preset-env.md

6f82595

Co-Authored-By: Nicolò Ribaudo <nicolo.ribaudo@gmail.com>

bowernite closed this Nov 4, 2022

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

@babel/preset-env: Clarify `useBuiltIns` usage and purpose #2067

@babel/preset-env: Clarify `useBuiltIns` usage and purpose #2067

bowernite commented Jul 19, 2019

netlify bot commented Jul 19, 2019 •

edited

nicolo-ribaudo commented Sep 5, 2019

zloirock Sep 5, 2019

bowernite Oct 1, 2019

zloirock Sep 5, 2019

bowernite Oct 1, 2019

patrick-mcdougle commented Sep 26, 2019

nicolo-ribaudo commented Sep 26, 2019

bowernite commented Oct 1, 2019

nicolo-ribaudo Oct 21, 2019 •

edited

nicolo-ribaudo Feb 26, 2020

bowernite Mar 3, 2020

nicolo-ribaudo Mar 3, 2020

bowernite Mar 6, 2020

nicolo-ribaudo Mar 7, 2020

bowernite Mar 10, 2020

existentialism left a comment

existentialism Mar 10, 2020

existentialism Mar 10, 2020


		Since `@babel/polyfill` was deprecated in 7.4.0, we recommend directly adding `core-js` and setting the version via the [`corejs`](#corejs) option.

	- `regenerator-runtime`: For generator and `async`/`await` support
	- `regenerator-runtime`: For generators and `async`/`await` in browsers without generators support

	This option enables a new plugin that replaces the `import "core-js"` and `import "regenerator-runtime/runtime"` statements with only what's needed from each of them, depending on the target environments.
	This option enables a plugin that replaces the `import "core-js"` and `import "regenerator-runtime/runtime"` statements with only what your target environments need from each of them.

@babel/preset-env: Clarify useBuiltIns usage and purpose #2067

@babel/preset-env: Clarify useBuiltIns usage and purpose #2067

Conversation

bowernite commented Jul 19, 2019

netlify bot commented Jul 19, 2019 • edited

nicolo-ribaudo commented Sep 5, 2019

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

patrick-mcdougle commented Sep 26, 2019

nicolo-ribaudo commented Sep 26, 2019

bowernite commented Oct 1, 2019

nicolo-ribaudo Oct 21, 2019 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

existentialism left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

@babel/preset-env: Clarify `useBuiltIns` usage and purpose #2067

@babel/preset-env: Clarify `useBuiltIns` usage and purpose #2067

netlify bot commented Jul 19, 2019 •

edited

nicolo-ribaudo Oct 21, 2019 •

edited