Killer feature request: Make Brunch STABLE

[lydell]

Description

The Brunch concept is super nice. Easy to install, easy to configure. Simple.

• Easy to use compilers.
• Great watch mode.
• Automatic npm installation.
• Awesome browser auto-reload.

Nothing super critical is missing from Brunch.

The issue is that Brunch keeps breaking. This is due to:

• Lack of tests.
• Lack of plugin API docs → plugins doing the wrong thing.
• Lack of npm releases and changelogs.

All of the time that I save from Brunch's super simple configuration is spent on hunting down the exact commits of Brunch and its plugins that work together and manages to compile my projects.

Examples

• Fix "sourcesContent" after optimizers are run #1634: Brunch relying on private parts of the source-map package. This caused source maps to break when that package was updated, but there were non tests to catch this.
• A 'joinTo' file named 'vendor.js' eats npm.static scripts #1621: A non-obvious feature that broke after a refactor of Brunch. A test could have caught it.
• brunch 2.9.1 seems to ignore defaultEnv: '*' #1546: Plugins breaking because of a mistake in a patch release. A basic integration test could have caught it.
• Fix error messages from the native compiler sass-brunch#120: Plugin being unsure of what it is supposed to return, resulting in no error messages from it. Better API documentation and some kind of "type-checking" tests could help.
• Fix error messages babel/babel-brunch#44: Same as the previous point.
• Fix source maps terser-brunch#39: Plugin being unsure of what parameters it receives, and what it is supposed to return. Caused source maps to be broken.
• brunch/terser-brunch@b0673d1: Cleanup after plugin being uncertain of what it receives.

Ideas

Monorepo

Gather Brunch, deppack and all official Brunch plugins into a monorepo.

• Makes it easier to run tests that check if a change in Brunch breaks a plugin.

• Ability to share test setup between plugins. Currently, changes seem to be
  made in one plugin, and then things are copied to others. If a mistake is made in the first plugin's setup, that propagates. Making changes to all plugins is super tedious.

  For example, I tried to add source map support to clean-css-brunch a few days ago. That caused the tests to fail with no error messages at all – because the test assertions made in .then() of promises causes the tests to fail because of timeout in the tests, not because of the assertions themselves! Super frustrating. I've seen this testing pattern in other plugins as well. This would be much easier to fix in a shared test setup. brunch/terser-brunch@db1ae32 fixes it for one particular plugin.

• Easier to make sweeping changes to all plugins.

• People don't have to think about which repo to open an issue for.

Tests

It feels common that a fix for one bug causes another bug, or a regression. I'm thinking that tests can help here.

• Every official plugin should be part of an integration test.
• Common combos of plugins should be tested, like sass-brunch + postcss-brunch.
• Unit tests, especially around source maps.
• Tests of the brunch watch log. This is where people look when their code fails to compile. It is very important that errors are show correct.

Flow

Use flow for type checking. I think this would be especially nice for plugins. They could check that they return what they are supposed to, and be sure of what they receive.

Plugin API docs improvements

• Document exactly what will be available in config passed to plugin constructors.

• Most plugin methods receive File objects. This is how it is documented:

  • path: "system path to the file." Quite good, but relative to what? Is it the
    path to the source code, or the output file? What is it when it comes from another plugin?
  • data: "file data as JS String." Perfect. We know both what it is, and its type.
  • map: "source map". What type is this? I think it is a SourceMapGenerator
    object from the source-map package. However, we returning a File from a plugin (in a Promise), it is supposed to be a string (I think!).

  It should also be documented that path and data must exist. (I think so, at least. Would it make sense otherwise?) And that map only may exist (depending on the "sourceMaps" config, and it previous plugins support source maps or not).

Simpler plugin source map handling

I suggest that the .map property of Files always are null or a plain JavaScript object. Not a SourceMapGenerator. Not a string.

• This is what most compilers take as input.
• It makes testing a lot easier. Just create a plain JavaScript object. No need to use require('source-map').SourceMapGenerator. That's harder – and isn't it an implementation detail?

A more radical idea is to not pass source maps to plugins at all. Only let them return source maps. Then, Brunch would be in charge of merging all the source maps. Much less to go wrong in every plugin.

Automatic releases

If we have tests and CI, it would be really great if releases of Brunch and plugins were fully automatic (including changelogs). I'm thinking about semantic-release.

Why? Fixes are often quickly merged. (Nice! 👍) But it is annoying for maintainers to make releases, resulting in people having to wait for a long time, or hunting down the speciic commits known to work.

For example, one of the most popular plugins, babel-brunch, still hasn't made a release with the fix for its error messages. People simply running npm i -D babel-brunch get basically no information at all when they make a syntax error mistake in their code.

Summary

Brunch is great. But it keeps breaking. I've presented a few solution ideas. Hopefully this can steer Brunch in a better direction.

I know that Brunch is open source and free of charge. People don't have unlimited time to work on it. I'm not complaining. I'm not demanding anything. I know that there are several awesome people working on Brunch at the moment. I like Brunch. And I hope the best for it. I'll help out as much as I can, too.

[tgallant]

Also better adherence to semver would be great. I've been hard pinning brunch versions (including plugins) in my package.json to avoid any breaking minor/patch releases