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

[Lyrkan]

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:

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

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

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)
;

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);

[weaverryan]

This looks absolutely perfect! Except for reversing the order... which is actually very minor. Great work!

[weaverryan]

We need to reverse the sorting: priority means that a higher number wins. So -10 should run after plugins with priority 0. This is also consistent with Symfony's priorities.

[Lyrkan]

Whoops, fixed :)

[weaverryan]

Great docs, btw. And nice idea to introduce the optional PluginPriorities.

[weaverryan]

Awesome, thank you @Lyrkan!

[stof]

I think we need to use different priorities for the core plugins, to allow hooking in the middle (for instance, we want to keep the manifest one late, but now, we can either register first or last only)

[Lyrkan]

@stof The reason for that choice is explained in #165 (comment): only the ManifestPlugin seems to require being placed after (nearly) everything else.

I'm not against setting a different priority for each plugin (I even thought about doing so initially) but is it really necessary?

[stof]

but then, at least the manifest plugin should have a different priority

[Lyrkan]

Adding a plugin before the manifest plugin can already be done by using:

Encore.addPlugin(
    new MyPlugin(),
    PluginPriorities.WebpackManifestPlugin + 1
);

If the order doesn't matter for the current other built-in plugins (I may be wrong on that though) it shouldn't be an issue to add the new plugin before all of them.

As en example #221 is going to use the CopyWebpackPlugin which needs to be added before the manifest plugin. In this case it makes sense to use a different priority.

[Lyrkan]

Just realized I said that the manifest plugin needed to be added after everything else in my first comment... I blame tiredness because that's definitely not what I meant.

It must only be placed after some plugins that emit additional assets, which is the case for the copy-webpack-plugin and the webpack-concat-plugin.

[stof]

@Lyrkan but this will add it before all core plugins. So currently, the priority system is only useful to put plugins before or after the core ones (which could be handled with a boolean rather than a priority)

[Lyrkan]

Currently yes since the order doesn't seem to matter for the core plugins we provide right now.

The idea behind that PR is to have something flexible enough in case other plugins (not necessarily core ones) require to be added before/after each others. And if later on we find out that an external plugin needs to be placed between two core plugins we could still modify those two plugins' priority.

#221 will also introduce the copy-webpack-plugin which will not have a priority of 0 since it has to be added before the manifest plugin (but yeah, that's still just an "add this one before anything else" situation).