Adding HoganJS to Brunch


As we described in an ealier post, Brunch is really just a simple way to build and develop any HTML5 application. Part of that simplicity is rooted in how it handles compilation of files with plugins.

Brunch doesn’t care

When you build on top of Brunch, a plugin actually handles the compilation and minification of each file. Brunch is responsible for watching for changes and making sure the appropriate plugin is notified of any changes.

For example, when Brunch comes across a file with a .coffee extension, it sends the contents of that file to the Coffeescript plugin for compilation and includes the result in the final application.

Lets take a look at the Coffeescript plugin code:

coffeescript = require 'coffee-script'
module.exports = class CoffeeScriptCompiler
  brunchPlugin: yes
  type: 'javascript'
  extension: 'coffee' # Here's where we determine what files to handle
  compile: (data, path, callback) ->
      result = coffeescript.compile data
    catch err
      error = err
      callback error, result

Now when we include any .coffee file in our project, the final result will be compiled automatically every time it changes. But this is a trivial example, lets try something a little more complex.

You’ve got some compilation in your mustache

While mustache is our preferred templating language, we also wanted to precompile the templates to Javascript, a capability found in both Handlebars and HoganJS.

Of course it’s a little more involved then that, because while they get precompiled and served as JS, they still rely on the HoganJS/Handlebars library to render in the browser.

Brunch has this handled as well, and we were able to quickly write a HoganJS plugin by adding an ‘include’ method to the module.

hogan = require 'hogan.js'
sysPath = require 'path'
module.exports = class HoganCompiler
  brunchPlugin: yes
  type: 'template'
  extension: 'mustache'

  # Returns a precompiled template with a 'render' function
  # Usage Example:
  # @$el.html(template({name: "mdp", city: "SF"}))
  compile: (data, path, callback) ->
      content = hogan.compile data, asString: yes
      result = "module.exports = new Hogan.Template(#{content});"
    catch err
      error = err
      callback error, result

  # Add '../node_modules/hogan.js/web/builds/2.0.0/template-2.0.0.js'
  # to vendor files.
  include: ->
    [(sysPath.join __dirname, '..', 'node_modules', 'hogan.js', 'web', 'builds', '2.0.0', 'template-2.0.0.js')]

Now when we use HoganCompiler in a project, Brunch will ensure that the file ‘template-2.0.0.js’ is automatically included in the output JS, and all the templates will be precompiled by the Hogan.js node library. All in less than 30 lines of code.

Final thoughts

The Brunch docs give the best overview of how to build your own plugins, but like many thing looking at some actual example plugins helped immensely. Here’s a quick list of some important ones you’ll probably want to use at some point:

Javascript Compilers

CSS Compilers


Photo courtesy of cote

Published: Sunday, May 6 2012
Author: Mark Percival

Death of a hashbang


A lot has been written about the hashbang, so instead of starting up the debate again, I’m instead going to simply show how we killed it, and why we think it never mattered in the first place.


The hashbang is no longer just something for web developers to argue about; it’s been implemented in a number of frameworks (most notably Backbone.js), and a number of large sites (Twitter being the best example). The idea is simple, in browsers that don’t support HTML pushstate, we revert to using an anchor (the hashbang - #!) in the URL to hold state.

So when you click on a link in Safari, you may see this in your URL bar:

But inside IE, your URL would display:!posts/123

The hashbang in this case prevents the page from reloading, and allows the Backbone router to handle running the appropriate action. But it’s a hack, and as you’ll see, it’s not entirely necessary.

Do we even need it?

While the hashbang does allow for quicker and smoother page transitions for older browsers, you still must handle someone directly hitting the URL. For example, if I wind up on /posts/12345, I could expect to hit refresh and have the page correctly reload the content and view.

So do I even need hashbangs for IE, or can I just let them load the link as they normally would?

It’s all about the expectations

The downside of this is obvious, the page is going to completely re-render for an older browser. But this was always the case before pushstate came into existance. Most of your assets will be cached at this point, so at worst it’ll take the time to 304 and run the Backbone.js applicaiton. And most importantly, for a user on an older browser, this reload is already expected. You’re not making their experience worse, but you are improving the experience for other users.

The nitty gritty

First, we should prevent the Hashbang from ever occuring by overriding Backbone’s ‘loadUrl’ method (Hat tip to Michael Franzkowiak):

Backbone.History.prototype.loadUrl = (fragmentOverride) ->
  fragment = this.fragment = this.getFragment(fragmentOverride, 
                                              this._wantsPushState &&
  matched = _.any this.handlers, (handler) ->
    if handler.route.test(fragment)
      return true

Then we need to find a way to make certain links pushstate capable.

  $(document).delegate "a.pushState", "click", (evt) ->
    # Get the anchor href and protocol
    href = $(this).attr("href")
    protocol = this.protocol + "//"

    # Ensure the protocol is not part of URL, meaning its relative.
    # Stop the event bubbling to ensure the link will not cause a page refresh.
    if href.substring(0, protocol.length) != protocol

      # Leading /'s break Backbone router nav
      if href.charAt(0) == '/'
        href = href.substr(1, href.length)
      if Backbone.history._hasPushState
        app.router.navigate href, trigger: true
        #Do Nothing

Now when an IE9 browser clicks on a link that has the class ‘pushState’ we simply allow the click to happen and the browser to load the new page. And likewise, when a pushState capable browser clicks the link, we prevent it from following it, and instead use Backbone’s router to navigate to the new view.

Should you implement it?

There’s no magic bullet here, and this isn’t going to end the debate on hashbangs. We’re deciding today to support the latest pushstate navigation at the expense of a slower (but expected) browsing experience for our IE users. And unlike starting with support for hashbangs, we can always add them back later, but we can never take them away.

Photo Credit Rick Harris

Published: Tuesday, April 3 2012
Author: Mark Percival

Sadly, A brunch that doesn't involve bacon


How it starts

When first launched, we had a fairly typical Rails stack, with the majority of view logic taking place on the server side. And like many web applications, as the application grew, we came to increasingly rely on Javascript for user interactions.

Whether it’s a simple ajaxy button or a complicated piece of form validation, if you’re not careful, your oh-so-DRY code on the Rails side soon becomes filled with duplicated client side functionality.

A move to Backbone.js

For us, the solution seemed to be the easy choice of moving to a more structured JS framework like Backbone.js. Backbone would allow us to move all the view rendering to the client side, and allow Rails to handle formatting and controlling the data coming from the database. But when the time came to get started on the implementation we soon found ourselves having to make even more decisions about directory structure, compilation, minification and deployment.

If you’re familiar with Backbone.js, then you’re probably also familiar with the amazing Addy Osmani and his book Backbone Fundementals. The advanced section has a great breakdown on ways to structure your app, as well as how to go about setting up tools like Require.js. And while this is a a great guide to handling some of the finer points of Backbone.js development, we weren’t in the position to make these decisions this early on in our development.

Brunch to the rescue

At it’s core, Brunch is just a Node.js based build tool for developing and deploying HTML5 apps. But like Rails, when you create a new Brunch project, you get a pretty awesome set of defaults for building your application.

Brunch handles our four main areas of concern. Compiling server side code (eg. Coffeescript/Roy), wrapping multiple files as common.js modules, building/minifying the final output, and allowing team members to quickly get started developing.

Rolling this out to the team is as simple as having each member ‘npm install’ the latest version of brunch, and then executing the brunch CLI tool. And since it’s based on npm, you can even explicitly list out your dependencies in package.json much as you would in a Gemfile.

What you get is a single compiled JS file which includes all the libraries you depend on, your backbone application code, and the common.js wrappers. And while you’re developing, Brunch will watch for changes and automatically recompile the code.

Where do we go from here

This is a big topic, and we’ve decided to publish a series of blog posts about Brunch and our development process. In the next few weeks, we’re going to touch on the following issues.

  • Death of a hashbang
  • Building on top of the Brunch API
  • Migrating from Rails to Rails/Backbone.js
  • Playing with alternate setups like Chaplin

Resources for your perusal

Photo courtesy of Martin Cathrae

Published: Friday, March 30 2012
Author: Mark Percival