Configure plugin order in config rather than rely on package.json order

[facboy]

It seems a bit fragile to have to rely on the order of declaration in package.json to determine the order that plugins are invoked in, given that npm --save reorders the dependencies alphabetically. I'm basing this on brunch-guide, and a cursory glance over the source code.

It would be nice if this could be overridden in config.

On another note, I'd quite like to be able to add locally-defined plugins without having them be a package in node_modules.

[paulmillr]

Agree. We should expose something like plugins: order.

As for the locally-defined plugins, our goal here is to not introduce new APIs that duplicate current ones. Maybe there's a way of loading your local package while still using package.json

[goshacmd]

Ok, manual ordering can make sense.

Could you expand on locally defined plugins? If you mean you want your project to both contain a plugin and use that, I can't see any problems with that. npm has a way to use packages from the file system:

{
  "devDependencies": {
    "my-super-plugin": "file:./my-super-plugin"
  }
}

[facboy]

Yeah, I'm currently using that npm mechanism, but if I'm editing the plugin I have to continually do an npm install to keep it up to date with the file system. I could also npm link it.

However, defining a separate package, while trivial, seems a bit overkill when I could just use a locally defined (eg in brunch-config) class/object and inject it into the config.

[goshacmd]

Well the use case we cover is editing your project and seeing the changes — not live-developing plugins. It does seem like a very niche one, and I'm not sure we want to complicate the internals and expose even more config for something that'll be barely used. cc @paulmillr?

[hgwood]

I think both the features presented in this issue would be very useful. Maybe something like this in the config?

plugins: {
  order: ['plugin1', 'plugin2'],
  locals: {
    plugin2: require('./plugin2') // ./plugin2.js exports a normal plugin class
  }
}

[michaelhogg]

❗ At the very least, the main documentation about plugins needs to state that plugins are executed in the order specified in package.json. ❗

(I found a mention of this here in the Brunch.io Guide, but it needs to be stated clearly in the main documentation on brunch.io.)

This seems extremely unintuitive, and I don't think I've encountered any other situation where the order of dependencies in package.json has any consequence.

In addition, regarding the dependencies and devDependencies objects in package.json, the JSON spec states:

An object is an unordered set of name/value pairs.

As mentioned in this Stack Overflow answer: "You cannot and should not rely on the ordering of elements within a JSON object."

---

For the benefit of people arriving here from a search engine:

brunch build was giving me a compilation error for a JS source file which exported an ES6 module:

error: Compiling of app/module.js failed. Line 5: Unexpected token

I found this error was being generated by Esprima on this line in javascript-brunch.

After investigating, I found the pipeline was using this array of compilers: [JavaScriptCompiler, BabelCompiler].

After further investigation, I found the ordering of the compilers was originating in loadPackages(), which loads the list of dependencies from package.json.

In my package.json, I had javascript-brunch before babel-brunch. So Esprima was trying to parse the JS source file before Babel had transpiled it 😕

[shvaikalesh]

Hey @michaelhogg, thanks for such detailed post. After #1522 is merged, you can use plugins.order to configure order of plugin execution:

plugins: {
  order: [
    'babel-brunch',
    'javascript-brunch',
  ],
},

Also, I have added a note to Brunch docs on the website. We would love to hear more thoughts from you on how to improve Brunch in the future. Thank you.

[michaelhogg]

@shvaikalesh: Awesome, thank you so much! 😀

I'm really enjoying using Brunch, and I've made a few contributions to eslint-brunch. I'll definitely continue to share contributions/feedback where I think things can be improved. Many thanks to the whole Brunch team for building such a great tool!

[shvaikalesh]

@michaelhogg After some thoughts and discussion, we've decided to eliminate the need of plugins.order. Instead we are going to drop javascript-brunch and css-brunch in the near future so the ordering detail you've encountered will never be a problem. We are aiming to make Brunch more transparent for users, but these plugins are extra stuff in the package.json we wanna get rid of. Will appreciate your feedback on this. Thanks.