minor #521 Allow to set @babel/preset-env's useBuiltIns option (Lyrkan)

This PR was merged into the master branch.

Discussion
----------

Allow to set @babel/preset-env's useBuiltIns option

This PR adds an `useBuiltIns` option to the second parameter of `Encore.configureBabel()` that sets the same option on the`@babel/preset-env` preset.

That option allows to change how the preset handles polyfills (fixes #444), for instance:

```js
Encore.configureBabel(() => {}, {
    // automatically import individual polyfills
    // where they are needed
    useBuiltIns: 'usage';
});
```

The PR also depreciates the `include_node_modules` option and replaces it by `includeNodeModules` since other methods (for instance `Encore.enableSassLoader()`) use camelCased names.

Commits
-------

6298a52 Allow to set @babel/preset-env useBuiltIns option and replace include_node_modules by includeNodeModules

Author: weaverryan

index.js

@@ -793,7 +793,11 @@ class Encore {
      *
      *      // ...or keep the default rule but only allow
      *      // *some* Node modules to be processed by Babel
-     *      include_node_modules: ['foundation-sites']
+     *      includeNodeModules: ['foundation-sites']
+     *
+     *      // automatically import polyfills where they
+     *      // are needed
+     *      useBuiltIns: 'usage'
      * });
      *
      * Supported options:
@@ -803,10 +807,18 @@ class Encore {
      *              processed by Babel (https://webpack.js.org/configuration/module/#condition).
      *              Cannot be used if the "include_node_modules" option is
      *              also set.
-     *      * {string[]} include_node_modules
+     *      * {string[]} includeNodeModules
      *              If set that option will include the given Node modules to
      *              the files that are processed by Babel. Cannot be used if
      *              the "exclude" option is also set.
+     *      * {'usage'|'entry'|false} useBuiltIns (default='entry')
+     *              Set the "useBuiltIns" option of @babel/preset-env that changes
+     *              how it handles polyfills (https://babeljs.io/docs/en/babel-preset-env#usebuiltins)
+     *              Using it with 'entry' will require you to import @babel/polyfill
+     *              once in your whole app and will result in that import being replaced
+     *              by individual polyfills. Using it with 'usage' will try to
+     *              automatically detect which polyfills are needed for each file and
+     *              add them accordingly.
      *
      * @param {function} callback
      * @param {object} encoreOptions

lib/WebpackConfig.js

@@ -81,7 +81,8 @@ class WebpackConfig {
             fonts: false
         };
         this.babelOptions = {
-            exclude: /(node_modules|bower_components)/
+            exclude: /(node_modules|bower_components)/,
+            useBuiltIns: 'entry',
         };
 
         // Features/Loaders options callbacks
@@ -327,13 +328,19 @@ class WebpackConfig {
         this.babelConfigurationCallback = callback;
 
         for (const optionKey of Object.keys(options)) {
+            let normalizedOptionKey = optionKey;
             if (optionKey === 'include_node_modules') {
+                logger.deprecation('configureBabel: "include_node_modules" is deprecated. Please use "includeNodeModules" instead.');
+                normalizedOptionKey = 'includeNodeModules';
+            }
+
+            if (normalizedOptionKey === 'includeNodeModules') {
                 if (Object.keys(options).includes('exclude')) {
-                    throw new Error('"include_node_modules" and "exclude" options can\'t be used together when calling configureBabel().');
+                    throw new Error('"includeNodeModules" and "exclude" options can\'t be used together when calling configureBabel().');
                 }
 
                 if (!Array.isArray(options[optionKey])) {
-                    throw new Error('Option "include_node_modules" passed to configureBabel() must be an Array.');
+                    throw new Error('Option "includeNodeModules" passed to configureBabel() must be an Array.');
                 }
 
                 this.babelOptions['exclude'] = (filePath) => {
@@ -356,10 +363,10 @@ class WebpackConfig {
                     // Exclude other modules
                     return true;
                 };
-            } else if (!(optionKey in this.babelOptions)) {
-                throw new Error(`Invalid option "${optionKey}" passed to configureBabel(). Valid keys are ${Object.keys(this.babelOptions).join(', ')}`);
+            } else if (!(normalizedOptionKey in this.babelOptions)) {
+                throw new Error(`Invalid option "${normalizedOptionKey}" passed to configureBabel(). Valid keys are ${[...Object.keys(this.babelOptions), 'includeNodeModules'].join(', ')}`);
             } else {
-                this.babelOptions[optionKey] = options[optionKey];
+                this.babelOptions[normalizedOptionKey] = options[optionKey];
             }
         }
     }

lib/loaders/babel.js

@@ -37,7 +37,7 @@ module.exports = {
                         modules: false,
                         targets: {},
                         forceAllTransforms: webpackConfig.isProduction(),
-                        useBuiltIns: 'entry'
+                        useBuiltIns: webpackConfig.babelOptions.useBuiltIns,
                     }]
                 ],
                 plugins: ['@babel/plugin-syntax-dynamic-import']

test/WebpackConfig.js

@@ -502,7 +502,7 @@ describe('WebpackConfig object', () => {
             expect(config.babelOptions.exclude).to.equal('foo');
         });
 
-        it('Calling with "include_node_modules" option', () => {
+        it('Calling with "includeNodeModules" option', () => {
             const config = createConfig();
             config.configureBabel(() => {}, { include_node_modules: ['foo', 'bar'] });
 
@@ -533,6 +533,13 @@ describe('WebpackConfig object', () => {
             }
         });
 
+        it('Calling with "useBuiltIns" option', () => {
+            const config = createConfig();
+            config.configureBabel(() => { }, { useBuiltIns: 'foo' });
+
+            expect(config.babelOptions.useBuiltIns).to.equal('foo');
+        });
+
         it('Calling with non-callback throws an error', () => {
             const config = createConfig();
 
@@ -558,19 +565,19 @@ describe('WebpackConfig object', () => {
             }).to.throw('Invalid option "fake_option" passed to configureBabel()');
         });
 
-        it('Calling with both "include_node_modules" and "exclude" options', () => {
+        it('Calling with both "includeNodeModules" and "exclude" options', () => {
             const config = createConfig();
 
             expect(() => {
-                config.configureBabel(() => {}, { exclude: 'foo', include_node_modules: ['bar', 'baz'] });
+                config.configureBabel(() => {}, { exclude: 'foo', includeNodeModules: ['bar', 'baz'] });
             }).to.throw('can\'t be used together');
         });
 
-        it('Calling with an invalid "include_node_modules" option value', () => {
+        it('Calling with an invalid "includeNodeModules" option value', () => {
             const config = createConfig();
 
             expect(() => {
-                config.configureBabel(() => {}, { include_node_modules: 'foo' });
+                config.configureBabel(() => {}, { includeNodeModules: 'foo' });
             }).to.throw('must be an Array');
         });
     });

test/config-generator.js

@@ -17,6 +17,7 @@ const MiniCssExtractPlugin = require('mini-css-extract-plugin');
 const ManifestPlugin = require('webpack-manifest-plugin');
 const CleanWebpackPlugin = require('clean-webpack-plugin');
 const webpack = require('webpack');
+const path = require('path');
 const logger = require('../lib/logger');
 
 const isWindows = (process.platform === 'win32');
@@ -861,6 +862,10 @@ describe('The config-generator function', () => {
 
             const jsRule = findRule(/\.jsx?$/, actualConfig.module.rules);
             expect(String(jsRule.exclude)).to.equal(String(/(node_modules|bower_components)/));
+
+            const babelLoader = jsRule.use.find(loader => loader.loader === 'babel-loader');
+            const babelEnvPreset = babelLoader.options.presets.find(([name]) => name === '@babel/preset-env');
+            expect(babelEnvPreset[1].useBuiltIns).to.equal('entry');
         });
 
         it('with configureBabel() and a different exclude rule', () => {
@@ -877,6 +882,40 @@ describe('The config-generator function', () => {
             const jsRule = findRule(/\.jsx?$/, actualConfig.module.rules);
             expect(String(jsRule.exclude)).to.equal(String(/foo/));
         });
+
+        it('with configureBabel() and some whitelisted modules', () => {
+            const config = createConfig();
+            config.outputPath = '/tmp/output/public-path';
+            config.publicPath = '/public-path';
+            config.addEntry('main', './main');
+            config.configureBabel(() => {}, {
+                includeNodeModules: ['foo']
+            });
+
+            const actualConfig = configGenerator(config);
+
+            const jsRule = findRule(/\.jsx?$/, actualConfig.module.rules);
+            expect(jsRule.exclude).to.be.a('Function');
+            expect(jsRule.exclude(path.join('test', 'node_modules', 'foo', 'index.js'))).to.be.false;
+            expect(jsRule.exclude(path.join('test', 'node_modules', 'bar', 'index.js'))).to.be.true;
+        });
+
+        it('with configureBabel() and a different useBuiltIns value', () => {
+            const config = createConfig();
+            config.outputPath = '/tmp/output/public-path';
+            config.publicPath = '/public-path';
+            config.addEntry('main', './main');
+            config.configureBabel(() => { }, {
+                useBuiltIns: 'usage'
+            });
+
+            const actualConfig = configGenerator(config);
+
+            const jsRule = findRule(/\.jsx?$/, actualConfig.module.rules);
+            const babelLoader = jsRule.use.find(loader => loader.loader === 'babel-loader');
+            const babelEnvPreset = babelLoader.options.presets.find(([name]) => name === '@babel/preset-env');
+            expect(babelEnvPreset[1].useBuiltIns).to.equal('usage');
+        });
     });
 
     describe('Test shouldSplitEntryChunks', () => {