feature #190 Add Encore.enableBuildNotifications() method (Lyrkan)

This PR was merged into the master branch.

Discussion
----------

Add Encore.enableBuildNotifications() method

This PR adds an `enableBuildNotifications()` method to the public API in order to use the `webpack-notifier` plugin (closes #187):

```js
// With default options
Encore.enableBuildNotifications();

// Conditionally
Encore.enableBuildNotifications(!Encore.isProduction());

// With custom options
Encore.enableBuildNotifications(true, (options) => {
    options.title = 'Foo';
});
```

The plugin is disabled by default and needs to be installed manually using `yarn add --dev webpack-notifier`.

Commits
-------

6fec895 Add Encore.enableBuildNotifications() method

Author: weaverryan

index.js

@@ -608,6 +608,30 @@ const publicApi = {
         return this;
     },
 
+    /**
+     * If enabled, display build notifications using
+     * webpack-notifier.
+     *
+     * https://github.com/Turbo87/webpack-notifier
+     *
+     *     Encore.enableBuildNotifications();
+     *
+     *     // or configure the webpack-notifier options
+     *     // https://github.com/Turbo87/webpack-notifier#configuration
+     *     Encore.enableBuildNotifications(true, function(options) {
+     *         options.title = 'Webpack build';
+     *     });
+     *
+     * @param {boolean} enabled
+     * @param {function} notifierPluginOptionsCallback
+     * @returns {exports}
+     */
+    enableBuildNotifications(enabled = true, notifierPluginOptionsCallback = () => {}) {
+        webpackConfig.enableBuildNotifications(enabled, notifierPluginOptionsCallback);
+
+        return this;
+    },
+
     /**
      * Call this if you wish to disable the default
      * images loader.

lib/WebpackConfig.js

@@ -60,6 +60,7 @@ class WebpackConfig {
         this.useVueLoader = false;
         this.useTypeScriptLoader = false;
         this.useForkedTypeScriptTypeChecking = false;
+        this.useWebpackNotifier = false;
 
         // Features/Loaders options
         this.sassOptions = {
@@ -89,6 +90,7 @@ class WebpackConfig {
         this.loaderOptionsPluginOptionsCallback = () => {};
         this.manifestPluginOptionsCallback = () => {};
         this.uglifyJsPluginOptionsCallback = () => {};
+        this.notifierPluginOptionsCallback = () => {};
     }
 
     getContext() {
@@ -389,6 +391,15 @@ class WebpackConfig {
         this.vueLoaderOptionsCallback = vueLoaderOptionsCallback;
     }
 
+    enableBuildNotifications(enabled = true, notifierPluginOptionsCallback = () => {}) {
+        if (typeof notifierPluginOptionsCallback !== 'function') {
+            throw new Error('Argument 2 to enableBuildNotifications() must be a callback function.');
+        }
+
+        this.useWebpackNotifier = enabled;
+        this.notifierPluginOptionsCallback = notifierPluginOptionsCallback;
+    }
+
     disableImagesLoader() {
         this.useImagesLoader = false;
     }

lib/config-generator.js

@@ -31,6 +31,7 @@ const definePluginUtil = require('./plugins/define');
 const uglifyPluginUtil = require('./plugins/uglify');
 const friendlyErrorPluginUtil = require('./plugins/friendly-errors');
 const assetOutputDisplay = require('./plugins/asset-output-display');
+const notifierPluginUtil = require('./plugins/notifier');
 const PluginPriorities = require('./plugins/plugin-priorities');
 
 class ConfigGenerator {
@@ -232,6 +233,8 @@ class ConfigGenerator {
 
         uglifyPluginUtil(plugins, this.webpackConfig);
 
+        notifierPluginUtil(plugins, this.webpackConfig);
+
         const friendlyErrorPlugin = friendlyErrorPluginUtil(this.webpackConfig);
         plugins.push({
             plugin: friendlyErrorPlugin,

lib/features.js

@@ -57,6 +57,11 @@ const features = {
         // vue-template-compiler is a peer dep of vue-loader
         packages: ['vue', 'vue-loader', 'vue-template-compiler'],
         description: 'load VUE files'
+    },
+    notifier: {
+        method: 'enableBuildNotifications()',
+        packages: ['webpack-notifier'],
+        description: 'display build notifications'
     }
 };
 

lib/plugins/notifier.js

@@ -0,0 +1,41 @@
+/*
+ * This file is part of the Symfony Webpack Encore package.
+ *
+ * (c) Fabien Potencier <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+'use strict';
+
+const pluginFeatures = require('../features');
+const PluginPriorities = require('./plugin-priorities');
+
+/**
+ * @param {Array} plugins
+ * @param {WebpackConfig} webpackConfig
+ * @return {void}
+ */
+module.exports = function(plugins, webpackConfig) {
+    if (!webpackConfig.useWebpackNotifier) {
+        return;
+    }
+
+    pluginFeatures.ensurePackagesExist('notifier');
+
+    const notifierPluginOptions = {
+        title: 'Webpack Encore'
+    };
+
+    webpackConfig.notifierPluginOptionsCallback.apply(
+        notifierPluginOptions,
+        [notifierPluginOptions]
+    );
+
+    const WebpackNotifier = require('webpack-notifier'); // eslint-disable-line
+    plugins.push({
+        plugin: new WebpackNotifier(notifierPluginOptions),
+        priority: PluginPriorities.WebpackNotifier
+    });
+};

lib/plugins/plugin-priorities.js

@@ -25,4 +25,5 @@ module.exports = {
     HashedModuleIdsPlugin: 0,
     NamedModulesPlugin: 0,
     WebpackChunkHash: 0,
+    WebpackNotifier: 0,
 };

package.json

@@ -75,6 +75,7 @@
     "vue": "^2.3.4",
     "vue-loader": "^12.2.1",
     "vue-template-compiler": "^2.3.4",
+    "webpack-notifier": "^1.5.0",
     "zombie": "^5.0.5"
   }
 }

test/WebpackConfig.js

@@ -604,6 +604,38 @@ describe('WebpackConfig object', () => {
         });
     });
 
+
+    describe('enableBuildNotifications', () => {
+        it('Calling method with default values', () => {
+            const config = createConfig();
+            config.enableBuildNotifications();
+
+            expect(config.useWebpackNotifier).to.be.true;
+        });
+
+        it('Calling method without enabling it', () => {
+            const config = createConfig();
+            config.enableBuildNotifications(false);
+
+            expect(config.useWebpackNotifier).to.be.false;
+        });
+
+        it('Calling method with options callback', () => {
+            const config = createConfig();
+            const callback = () => {};
+            config.enableBuildNotifications(true, callback);
+
+            expect(config.useWebpackNotifier).to.be.true;
+            expect(config.notifierPluginOptionsCallback).to.equal(callback);
+        });
+
+        it('Calling method with invalid options callback', () => {
+            const config = createConfig();
+
+            expect(() => config.enableBuildNotifications(true, 'FOO')).to.throw('must be a callback function');
+        });
+    });
+
     describe('addPlugin', () => {
         it('extends the current registered plugins', () => {
             const config = createConfig();

test/index.js

@@ -215,6 +215,15 @@ describe('Public API', () => {
 
     });
 
+    describe('enableBuildNotifications', () => {
+
+        it('must return the API object', () => {
+            const returnedValue = api.enableBuildNotifications();
+            expect(returnedValue).to.equal(api);
+        });
+
+    });
+
     describe('disableImagesLoader', () => {
 
         it('must return the API object', () => {

test/plugins/notifier.js

@@ -0,0 +1,70 @@
+/*
+ * This file is part of the Symfony Webpack Encore package.
+ *
+ * (c) Fabien Potencier <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+'use strict';
+
+const expect = require('chai').expect;
+const WebpackNotifier = require('webpack-notifier');
+const WebpackConfig = require('../../lib/WebpackConfig');
+const RuntimeConfig = require('../../lib/config/RuntimeConfig');
+const notifierPluginUtil = require('../../lib/plugins/notifier');
+
+function createConfig() {
+    const runtimeConfig = new RuntimeConfig();
+    runtimeConfig.context = __dirname;
+    runtimeConfig.babelRcFileExists = false;
+
+    return new WebpackConfig(runtimeConfig);
+}
+
+describe('plugins/notifier', () => {
+    it('disabled by default', () => {
+        const config = createConfig();
+        const plugins = [];
+
+        notifierPluginUtil(plugins, config);
+        expect(plugins.length).to.equal(0);
+    });
+
+    it('explicitly disabled', () => {
+        const config = createConfig();
+        const plugins = [];
+
+        config.enableBuildNotifications(false);
+
+        notifierPluginUtil(plugins, config);
+        expect(plugins.length).to.equal(0);
+    });
+
+    it('enabled with default settings', () => {
+        const config = createConfig();
+        const plugins = [];
+
+        config.enableBuildNotifications();
+
+        notifierPluginUtil(plugins, config);
+        expect(plugins.length).to.equal(1);
+        expect(plugins[0].plugin).to.be.instanceof(WebpackNotifier);
+        expect(plugins[0].plugin.options.title).to.equal('Webpack Encore');
+    });
+
+    it('enabled with options callback', () => {
+        const config = createConfig();
+        const plugins = [];
+
+        config.enableBuildNotifications(true, (options) => {
+            options.title = 'foo';
+        });
+
+        notifierPluginUtil(plugins, config);
+        expect(plugins.length).to.equal(1);
+        expect(plugins[0].plugin).to.be.instanceof(WebpackNotifier);
+        expect(plugins[0].plugin.options.title).to.equal('foo');
+    });
+});