feature #177 Add a priority parameter to the Encore.addPlugin() method (Lyrkan)

This PR was merged into the master branch.

Discussion
----------

Add a priority parameter to the Encore.addPlugin() method

Following the discussion in #165 this PR adds a `priority` parameter to the `Encore.addPlugin()` method in order to allow people to choose where their custom plugins will be added in the generated Webpack config (fixes #163).

__Examples:__

```js
const Encore = require('@symfony/webpack-encore');

// Without setting the priority a plugin will be
// appended to the other plugins.
Encore.addPlugin(new CustomPlugin());
```

```js
const Encore = require('@symfony/webpack-encore');

// If two plugins need to be sorted relatively to
// eachother (CustomPluginB will be placed before
// CustomPluginA):
Encore
    .addPlugin(new CustomPluginA(), 100);
    .addPlugin(new CustomPluginB(), 50)
;
```

```js
const Encore = require('@symfony/webpack-encore');
const PluginPriorities = require('@symfony/webpack-encore/lib/plugins/plugin-priorities.js');

// For now all plugins added by Encore have a
// priority of 0 (the same as the default priority for
// custom plugins), but constants are available in
// order to avoid BC breaks:
Encore.addPlugin(new CustomPlugin(), PluginPriorities.UglifyJsPlugin);
```

Commits
-------

b7461a1 Add a priority parameter to the Encore.addPlugin() method

Author: weaverryan

index.js

@@ -269,11 +269,35 @@ const publicApi = {
      * For example, if you want to add the "webpack.IgnorePlugin()", then:
      *      .addPlugin(new webpack.IgnorePlugin(requestRegExp, contextRegExp))
      *
+     * By default custom plugins are added after the ones managed by Encore
+     * but you can also set a priority to define where your plugin will be
+     * added in the generated Webpack config.
+     *
+     * For example, if a plugin has a priority of 0 and you want to add
+     * another plugin after it, then:
+     *
+     *      .addPlugin(new MyWebpackPlugin(), -10)
+     *
+     * The priority of each plugin added by Encore can be found in the
+     * "lib/plugins/plugin-priorities.js" file. It is recommended to use
+     * these constants if you want to add a plugin using the same priority
+     * as one managed by Encore in order to avoid backward compatibility
+     * breaks.
+     *
+     * For example, if you want one of your plugins to have the same priority
+     * than the DefinePlugin:
+     *
+     *      const Encore = require('@symfony/webpack-encore');
+     *      const PluginPriorities = require('@symfony/webpack-encore/lib/plugins/plugin-priorities.js');
+     *
+     *      Encore.addPlugin(new MyWebpackPlugin(), PluginPriorities.DefinePlugin);
+     *
      * @param {string} plugin
+     * @param {number} priority
      * @return {exports}
      */
-    addPlugin(plugin) {
-        webpackConfig.addPlugin(plugin);
+    addPlugin(plugin, priority = 0) {
+        webpackConfig.addPlugin(plugin, priority);
 
         return this;
     },

lib/WebpackConfig.js

@@ -252,8 +252,15 @@ class WebpackConfig {
         this.styleEntries.set(name, src);
     }
 
-    addPlugin(plugin) {
-        this.plugins.push(plugin);
+    addPlugin(plugin, priority = 0) {
+        if (typeof priority !== 'number') {
+            throw new Error('Argument 2 to addPlugin() must be a number.');
+        }
+
+        this.plugins.push({
+            plugin: plugin,
+            priority: priority
+        });
     }
 
     addLoader(loader) {

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 PluginPriorities = require('./plugins/plugin-priorities');
 
 class ConfigGenerator {
     /**
@@ -207,7 +208,7 @@ class ConfigGenerator {
     }
 
     buildPluginsConfig() {
-        let plugins = [];
+        const plugins = [];
 
         extractTextPluginUtil(plugins, this.webpackConfig);
 
@@ -232,15 +233,31 @@ class ConfigGenerator {
         uglifyPluginUtil(plugins, this.webpackConfig);
 
         const friendlyErrorPlugin = friendlyErrorPluginUtil(this.webpackConfig);
-        plugins.push(friendlyErrorPlugin);
+        plugins.push({
+            plugin: friendlyErrorPlugin,
+            priority: PluginPriorities.FriendlyErrorsWebpackPlugin
+        });
 
         assetOutputDisplay(plugins, this.webpackConfig, friendlyErrorPlugin);
 
         this.webpackConfig.plugins.forEach(function(plugin) {
             plugins.push(plugin);
         });
 
-        return plugins;
+        // Return sorted plugins
+        return plugins
+            .map((plugin, position) => Object.assign({}, plugin, { position: position }))
+            .sort((a, b) => {
+                // Keep the original order if two plugins have the same priority
+                if (a.priority === b.priority) {
+                    return a.position - b.position;
+                }
+
+                // A plugin with a priority of -10 will be placed after one
+                // that has a priority of 0.
+                return b.priority - a.priority;
+            })
+            .map((plugin) => plugin.plugin);
     }
 
     buildStatsConfig() {

lib/plugins/asset-output-display.js

@@ -11,6 +11,7 @@
 
 const pathUtil = require('../config/path-util');
 const AssetOutputDisplayPlugin = require('../friendly-errors/asset-output-display-plugin');
+const PluginPriorities = require('./plugin-priorities');
 
 /**
  * Updates plugins array passed adding AssetOutputDisplayPlugin instance
@@ -26,5 +27,8 @@ module.exports = function(plugins, webpackConfig, friendlyErrorsPlugin) {
     }
 
     const outputPath = pathUtil.getRelativeOutputPath(webpackConfig);
-    plugins.push(new AssetOutputDisplayPlugin(outputPath, friendlyErrorsPlugin));
+    plugins.push({
+        plugin: new AssetOutputDisplayPlugin(outputPath, friendlyErrorsPlugin),
+        priority: PluginPriorities.AssetOutputDisplayPlugin
+    });
 };

lib/plugins/clean.js

@@ -10,6 +10,7 @@
 'use strict';
 
 const CleanWebpackPlugin = require('clean-webpack-plugin');
+const PluginPriorities = require('./plugin-priorities');
 
 /**
  * Updates plugins array passed adding CleanWebpackPlugin instance
@@ -34,8 +35,11 @@ module.exports = function(plugins, webpackConfig) {
         [cleanWebpackPluginOptions]
     );
 
-    plugins.push(new CleanWebpackPlugin(
-        webpackConfig.cleanWebpackPluginPaths,
-        cleanWebpackPluginOptions
-    ));
+    plugins.push({
+        plugin: new CleanWebpackPlugin(
+            webpackConfig.cleanWebpackPluginPaths,
+            cleanWebpackPluginOptions
+        ),
+        priority: PluginPriorities.CleanWebpackPlugin
+    });
 };

lib/plugins/commons-chunks.js

@@ -10,6 +10,7 @@
 'use strict';
 
 const webpack = require('webpack');
+const PluginPriorities = require('./plugin-priorities');
 
 /**
  * @param {Array} plugins
@@ -23,18 +24,21 @@ module.exports = function(plugins, webpackConfig) {
     }
 
     // if we're extracting a vendor chunk, set it up!
-    plugins.push(new webpack.optimize.CommonsChunkPlugin({
-        name: [
-            webpackConfig.sharedCommonsEntryName,
-            /*
-             * Always dump a 2nd file - manifest.json that
-             * will contain the webpack manifest information.
-             * This changes frequently, and without this line,
-             * it would be packaged inside the "shared commons entry"
-             * file - e.g. vendor.js, which would prevent long-term caching.
-             */
-            'manifest'
-        ],
-        minChunks: Infinity,
-    }));
+    plugins.push({
+        plugin: new webpack.optimize.CommonsChunkPlugin({
+            name: [
+                webpackConfig.sharedCommonsEntryName,
+                /*
+                * Always dump a 2nd file - manifest.json that
+                * will contain the webpack manifest information.
+                * This changes frequently, and without this line,
+                * it would be packaged inside the "shared commons entry"
+                * file - e.g. vendor.js, which would prevent long-term caching.
+                */
+                'manifest'
+            ],
+            minChunks: Infinity,
+        }),
+        priority: PluginPriorities.CommonsChunkPlugin
+    });
 };

lib/plugins/define.js

@@ -10,6 +10,7 @@
 'use strict';
 
 const webpack = require('webpack');
+const PluginPriorities = require('./plugin-priorities');
 
 /**
  * @param {Array} plugins
@@ -28,5 +29,8 @@ module.exports = function(plugins, webpackConfig) {
         [definePluginOptions]
     );
 
-    plugins.push(new webpack.DefinePlugin(definePluginOptions));
+    plugins.push({
+        plugin: new webpack.DefinePlugin(definePluginOptions),
+        priority: PluginPriorities.DefinePlugin
+    });
 };

lib/plugins/delete-unused-entries.js

@@ -10,6 +10,7 @@
 'use strict';
 
 const DeleteUnusedEntriesJSPlugin = require('../webpack/delete-unused-entries-js-plugin');
+const PluginPriorities = require('./plugin-priorities');
 
 /**
  * @param {Array} plugins
@@ -18,8 +19,11 @@ const DeleteUnusedEntriesJSPlugin = require('../webpack/delete-unused-entries-js
  */
 module.exports = function(plugins, webpackConfig) {
 
-    plugins.push(new DeleteUnusedEntriesJSPlugin(
-        // transform into an Array
-        [... webpackConfig.styleEntries.keys()]
-    ));
+    plugins.push({
+        plugin: new DeleteUnusedEntriesJSPlugin(
+            // transform into an Array
+            [... webpackConfig.styleEntries.keys()]
+        ),
+        priority: PluginPriorities.DeleteUnusedEntriesJSPlugin
+    });
 };

lib/plugins/extract-text.js

@@ -10,6 +10,7 @@
 'use strict';
 
 const ExtractTextPlugin = require('extract-text-webpack-plugin');
+const PluginPriorities = require('./plugin-priorities');
 
 /**
  * @param {Array} plugins
@@ -49,5 +50,8 @@ module.exports = function(plugins, webpackConfig) {
         [extractTextPluginOptions]
     );
 
-    plugins.push(new ExtractTextPlugin(extractTextPluginOptions));
+    plugins.push({
+        plugin: new ExtractTextPlugin(extractTextPluginOptions),
+        priority: PluginPriorities.ExtractTextWebpackPlugin
+    });
 };

lib/plugins/forked-ts-types.js

@@ -10,6 +10,7 @@
 'use strict';
 
 const ForkTsCheckerWebpackPlugin = require('fork-ts-checker-webpack-plugin'); // eslint-disable-line
+const PluginPriorities = require('./plugin-priorities');
 
 /**
  * @param {WebpackConfig} webpackConfig
@@ -25,5 +26,8 @@ module.exports = function(webpackConfig) {
         [config]
     );
 
-    webpackConfig.addPlugin(new ForkTsCheckerWebpackPlugin(config));
+    webpackConfig.addPlugin(
+        new ForkTsCheckerWebpackPlugin(config),
+        PluginPriorities.ForkTsCheckerWebpackPlugin
+    );
 };