Why I defected from Broccoli

broccoli-gobble.md

This is in answer to @ebryn's tweet: https://twitter.com/ebryn/status/505401187936780288

Having written Gobble, I want to make it plain that I'm actually a big Broccoli fan - I've extolled its virtues far and wide, and we used it at theguardian.com and with Ractive for some time. My appreciation has only increased since discovering how bloody awkward it is to deal with the filesystem for anything non-trivial (and I thought web development was fraught). I'm fully aware that there are areas where Broccoli easily beats Gobble (e.g. Windows support), and that it's far more battle-tested.

But there are things about Broccoli that grated, and which eventually drove me to create a replacement.

Weird, hard to reproduce errors

We used Broccoli on a large and complex project at the Guardian recently. As it grew, we started to get strange errors, e.g. ENOENT errors on files that Broccoli was supposed to be managing. Although these could be fixed by just restarting Broccoli, it was annoying, and reduced our confidence in our workflow. It wasn't practical to raise issues because a) we were on tight deadlines and b) the difficulty of reproducing them. Generally speaking, I think Broccoli could handle errors more gracefully - for example an EADDRINUSE error could be turned into a helpful 'are you already running Broccoli? port xxxx is already in use' message.

Build debuggability

Complex builds are hard to get right first time. I often wished Broccoli would provide more help in this regard - trawling through the tmp dir, to try and find which of the many some_transform-tmp_dest_dir-BCX5ngJQ.tmp directories (which rarely seem to get cleaned up?) is the most recent one, is just about the only way to start figuring things out. You can export part of your tree with broccoli-export-tree (if you know about it), but AFAICT you have to do this sort of thing...

tree = mergeTrees([ tree, exportTree( tree ) ])

...which is super-awkward.

Docs

Believe me, I know docs are incredibly hard to keep complete and up-to-date. But I'm not a stupid guy, yet it took me several goes to figure out how to use Broccoli for anything non-trivial - I stuck with it because I was impressed by Jo's original blog post (and also because Erik was raving about it :-). Even then, I had to get help. Other devs have reported similar. Many would just give up.

Writing plugins

This is partly the same point as above - it's not clear how to get started writing plugins. But it's also true that Broccoli plugins involve a bit of unnecessary boilerplate. Not as much as most other tools (I'm looking at you, Grunt and Gulp), but still enough that I kept asking 'am I doing this right?'.

Excessive modularity

I feel like this is endemic within the node.js community. An example of what I mean: in all but the most contrived situations, I'm going to need to do at least two things with my build - selecting some files from the filesystem, and merging several trees into one. Yet that core functionality lives in two modules that are separate from Broccoli itself!

Non-chaining API

This isn't a flaw in Broccoli, just a matter of personal taste - I prefer being able to use a chaining API. Among other things, it seems like a more natural expression of what's actually happening:

// instead of this...
var z = compileAsZ( compileAsY( compileAsX( tree ) ) );

// ...or this...
var x = compileAsX( tree );
var y = compileAsY( x );
var z = compileAsZ( y );

// ...I like being able to do this
var z = tree.transform( 'x' ).transform( 'y' ).transform( 'z' );

So those are my reasons. Very happy to talk over them more if you have any questions.