feature #217 Add Encore.addAliases and Encore.addExternals methods (Lyrkan)

This PR was merged into the master branch.

Discussion
----------

Add Encore.addAliases and Encore.addExternals methods

This PR adds two new methods to the API (closes #200):

* **`Encore.addAliases`**: Adds the given values to the `resolve.alias` setting of the generated config
* **`Encore.addExternals`**: Adds the given values to the `external` setting of the generated config

Commits
-------

eefe8a4 Add Encore.addAliases and Encore.addExternals methods

Author: weaverryan

index.js

@@ -328,6 +328,51 @@ const publicApi = {
         return this;
     },
 
+    /**
+     * Allow you to add aliases that will be used by
+     * Webpack when trying to resolve modules.
+     *
+     * See https://webpack.js.org/configuration/resolve/#resolve-alias
+     *
+     * For example:
+     *
+     *      Encore.addAliases({
+     *          Utilities: path.resolve(__dirname, 'src/utilities/'),
+     *          Templates: path.resolve(__dirname, 'src/templates/')
+     *      })
+     *
+     * @param {object} aliases
+     *
+     * @returns {exports}
+     */
+    addAliases(aliases) {
+        webpackConfig.addAliases(aliases);
+
+        return this;
+    },
+
+    /**
+     * Allow you to exclude some dependencies from the output bundles.
+     *
+     * See https://webpack.js.org/configuration/externals/
+     *
+     * For example:
+     *
+     *      Encore.addExternals({
+     *          jquery: 'jQuery',
+     *          react: 'react'
+     *      })
+     *
+     * @param {object} externals
+     *
+     * @returns {exports}
+     */
+    addExternals(externals) {
+        webpackConfig.addExternals(externals);
+
+        return this;
+    },
+
     /**
      * When enabled, files are rendered with a hash based
      * on their contents (e.g. main.a2b61cc.js)

lib/WebpackConfig.js

@@ -45,6 +45,8 @@ class WebpackConfig {
         this.sharedCommonsEntryName = null;
         this.providedVariables = {};
         this.configuredFilenames = {};
+        this.aliases = {};
+        this.externals = {};
 
         // Features/Loaders flags
         this.useVersioning = false;
@@ -271,6 +273,22 @@ class WebpackConfig {
         this.loaders.push(loader);
     }
 
+    addAliases(aliases = {}) {
+        if (typeof aliases !== 'object') {
+            throw new Error('Argument 1 to addAliases() must be an object.');
+        }
+
+        Object.assign(this.aliases, aliases);
+    }
+
+    addExternals(externals = {}) {
+        if (typeof externals !== 'object') {
+            throw new Error('Argument 1 to addExternals() must be an object.');
+        }
+
+        Object.assign(this.externals, externals);
+    }
+
     enableVersioning(enabled = true) {
         this.useVersioning = enabled;
     }

lib/config-generator.js

@@ -77,7 +77,7 @@ class ConfigGenerator {
 
         config.resolve = {
             extensions: ['.js', '.jsx', '.vue', '.ts', '.tsx'],
-            alias: {}
+            alias: this.webpackConfig.aliases
         };
 
         if (this.webpackConfig.useVueLoader) {
@@ -89,6 +89,8 @@ class ConfigGenerator {
             config.resolve.alias['react-dom'] = 'preact-compat';
         }
 
+        config.externals = this.webpackConfig.externals;
+
         return config;
     }
 

test/WebpackConfig.js

@@ -709,6 +709,56 @@ describe('WebpackConfig object', () => {
         });
     });
 
+    describe('addAliases', () => {
+        it('Adds new aliases', () => {
+            const config = createConfig();
+
+            expect(config.aliases).to.deep.equals({});
+
+            config.addAliases({ 'testA': 'src/testA', 'testB': 'src/testB' });
+            config.addAliases({ 'testC': 'src/testC' });
+
+            expect(config.aliases).to.deep.equals({
+                'testA': 'src/testA',
+                'testB': 'src/testB',
+                'testC': 'src/testC'
+            });
+        });
+
+        it('Calling it with an invalid argument', () => {
+            const config = createConfig();
+
+            expect(() => {
+                config.addAliases('foo');
+            }).to.throw('must be an object');
+        });
+    });
+
+    describe('addExternals', () => {
+        it('Adds new externals', () => {
+            const config = createConfig();
+
+            expect(config.externals).to.deep.equals({});
+
+            config.addExternals({ 'jquery': 'jQuery', 'react': 'react' });
+            config.addExternals({ 'lodash': 'lodash' });
+
+            expect(config.externals).to.deep.equals({
+                'jquery': 'jQuery',
+                'react': 'react',
+                'lodash': 'lodash'
+            });
+        });
+
+        it('Calling it with an invalid argument', () => {
+            const config = createConfig();
+
+            expect(() => {
+                config.addExternals('foo');
+            }).to.throw('must be an object');
+        });
+    });
+
     describe('disableImagesLoader', () => {
         it('Disable default images loader', () => {
             const config = createConfig();

test/config-generator.js

@@ -346,6 +346,64 @@ describe('The config-generator function', () => {
         });
     });
 
+    describe('addAliases() adds new aliases', () => {
+        it('without addAliases()', () => {
+            const config = createConfig();
+            config.outputPath = '/tmp/output/public-path';
+            config.publicPath = '/public-path';
+
+            const actualConfig = configGenerator(config);
+
+            expect(actualConfig.resolve.alias).to.deep.equals({});
+        });
+
+        it('with addAliases()', () => {
+            const config = createConfig();
+            config.outputPath = '/tmp/output/public-path';
+            config.publicPath = '/public-path';
+            config.addAliases({
+                'testA': 'src/testA',
+                'testB': 'src/testB'
+            });
+
+            const actualConfig = configGenerator(config);
+
+            expect(actualConfig.resolve.alias).to.deep.equals({
+                'testA': 'src/testA',
+                'testB': 'src/testB'
+            });
+        });
+    });
+
+    describe('addExternals() adds new externals', () => {
+        it('without addExternals()', () => {
+            const config = createConfig();
+            config.outputPath = '/tmp/output/public-path';
+            config.publicPath = '/public-path';
+
+            const actualConfig = configGenerator(config);
+
+            expect(actualConfig.externals).to.deep.equals({});
+        });
+
+        it('with addExternals()', () => {
+            const config = createConfig();
+            config.outputPath = '/tmp/output/public-path';
+            config.publicPath = '/public-path';
+            config.addExternals({
+                'jquery': 'jQuery',
+                'react': 'react'
+            });
+
+            const actualConfig = configGenerator(config);
+
+            expect(actualConfig.externals).to.deep.equals({
+                'jquery': 'jQuery',
+                'react': 'react'
+            });
+        });
+    });
+
     describe('.js rule receives different configuration', () => {
         it('Use default config', () => {
             const config = createConfig();

test/index.js

@@ -89,6 +89,24 @@ describe('Public API', () => {
 
     });
 
+    describe('addAliases', () => {
+
+        it('must return the API object', () => {
+            const returnedValue = api.addAliases({});
+            expect(returnedValue).to.equal(api);
+        });
+
+    });
+
+    describe('addExternals', () => {
+
+        it('must return the API object', () => {
+            const returnedValue = api.addExternals({});
+            expect(returnedValue).to.equal(api);
+        });
+
+    });
+
     describe('enableVersioning', () => {
 
         it('must return the API object', () => {