Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Clarify docs about env "useBuiltIns" behavior and common uses. #2425

Open
wants to merge 1 commit into
base: main
Choose a base branch
from

Conversation

AndrewSouthpaw
Copy link

I think a lot of people wind up at this section of the docs and can get pretty easily overwhelmed by all the details about polyfills, core-js, etc.

My intent was to provide some more language around how the system works, and what people "probably" will want to choose the majority of the time, to guide them in the right direction.

I also switched the order of the detailed sections on usage and entry so that it reflects the order of the options presented (usage, entry, false).

@netlify
Copy link

netlify bot commented Dec 1, 2020

Deploy preview for babel ready!

Built without sensitive environment variables with commit 73289b7

https://deploy-preview-2425--babel.netlify.app


# or
Generally, `"usage"` meets the needs of most users by only including the polyfills that are needed.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This might be a tricky recommendation for users who have dependencies in node_modules that rely on certain built-ins being available that aren't run through Babel.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I hadn't even considered that. Sounds like a nuance worth mentioning, I'll include that...

@@ -264,18 +264,85 @@ This option is useful for "blacklisting" a transform like `@babel/plugin-transfo

`"usage"` | `"entry"` | `false`, defaults to `false`.

This option configures how `@babel/preset-env` handles polyfills.
This option configures how `@babel/preset-env` handles polyfills and whether optimizations are applied to only include polyfills that are needed.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What about something like:

Suggested change
This option configures how `@babel/preset-env` handles polyfills and whether optimizations are applied to only include polyfills that are needed.
This option configures `@babel/preset-env` to only include the polyfills needed by your target environment(s). This can either include all polyfills needed to mimic a ES2020 environment (`entry`), or only include polyfills as they are needed/used in each file (`usage`).

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Riffing on that a bit more, how about this? I dropped mention of ES2020 because that will become outdated eventually.

Suggested change
This option configures how `@babel/preset-env` handles polyfills and whether optimizations are applied to only include polyfills that are needed.
This option configures `@babel/preset-env` to only include the polyfills needed by your target environment(s) to mimic the latest JS-spec environment. Options are to include polyfills as they are needed/used in each file (`usage`) or include polyfills at the entrypoint to your application (`entry`).

Given the nuance you mention, I'm not exactly clear on what are the pros/cons of each? If usage wouldn't help people in the case about node_modules you mentioned above, is there a reason people wouldn't always just use entry? If I understand that aspect more, then I think we could get a better synopsis out to users.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There are certainly people who do compile their node_modules (or if you're sure that your deps don't need to be polyfilled) to get the full benefit of usage, it's just a caveat that people may not be aware of when they're setting up Babel for their project.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That totally makes sense. I'm just trying to understand, when you say "the full benefit of usage", what is that benefit? Are there benefits of usage over entry? I think that would be good to showcase.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants