Bug report

Bug in Babel polyfill documentation for webpack

Input Code

Repo

Revelation posted in babel-loader

Babel/Babylon Configuration (.babelrc, package.json, cli command)

.babelrc

{
  "presets": [
  	[
      "@babel/preset-env",
    	{
        "useBuiltIns": "usage",
        "forceAllTransforms": true,
        "ignoreBrowserslistConfig": false,
        "modules": false,
        "debug": true
      }
    ]
  ]
}

.browserslistrc

[production]
last 1 Chrome version

[development]
last 1 Chrome version

or

[production]
> 0.0001%

[development]
> 0.0001%

webpack.config.js

entry: {
    site: [
      '@babel/polyfill',
      path.join(__dirname, 'src/site.js')
    ],
    // ...
  }

Expected Behavior

When '@babel/polyfill' is included in webpack entry point as per documentation and "useBuiltIns": "usage" is used then then all polyfills are stripped and only ones found by union of usage within the code and specified browserlist are left.

When '@babel/polyfill' is included in webpack entry point as per documentation and "useBuiltIns": "entry" is used then then all polyfills are stripped and only ones found by specified browserslist are left.

Current Behavior

When '@babel/polyfill' is included in webpack entry point as per documentation and "useBuiltIns": "usage" is used then then all polyfills will be included as well as ones found by usage and browserlist combo resulting in monstrous bundle.

When '@babel/polyfill' is included in webpack entry point as per documentation and "useBuiltIns": "entry" is used then then @babel/polyfill is not found, which effectively means that babel cannot strip unneeded, thus all polyfills will be included in the bundle resulting in monstrous bundle.

Possible Solution

Make changes in Polyfill documentation as well as in babel-preset-env documentation

The current statement

With webpack.config.js, add babel-polyfill to your entry array

is correct only in one of three possible useBuiltIns settings (so in 2 cases out of 3 users are building all polyfills into their bundle).

They should state that:

• If @babel/preset-env has "useBuiltIns": "usage" then babel polyfill should not be included neither in source nor webpack entry (but it has to be installed of course). Browserslist configuration should be present.
• If @babel/preset-env has "useBuiltIns": "entry" then babel polyfill should be included in source, not webpack entry. Browserslist configuration should be present.
• If @babel/preset-env does not have "useBuiltIns" key or it is explicitly set to false "useBuiltIns": false then babel polyfill should be included in webpack entry, but it can be included also in source (the latter being unadvised due to hoisting).

Context

By trusting documentation I have deployed unnecessary large bundles although I have targeted new browsers.
I use .browserslistrc file as it is also used by PostCSS autoprefixer (JS and CSS features stay in sync).

Your Environment