Using Brunch with Middleman

Warning - Old content ahead!

This page has been marked as a legacy post. This means it's quite old (from 2016) and probably out of date. Take it with a grain of salt!

Update: I've just released a Middleman template that does the hardwork for you. Check it out on my Github: Read on for an explanation of how it works.

I recently started a new blog in an area unrelated to Web Development and was pleased to find that with the release of Middleman v4 you can now specify your own external asset pipeline.

I decided to give Brunch a shot - since I already use it with Elixir's Phoenix Framework and I was pleasantly surprised by how easy it was to get everything set up.

First of all, here's my package.json file - note that Bourbon, Bourbon Neat, Turbolinks, and Font Awesome are all optional but will help provide an example of how to set up various libraries with Brunch and Middleman.

  "name": "middlemanblog",
  "version": "1.0.0",
  "description": "",
  "main": "brunch-config.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  "author": "",
  "license": "MIT",
  "devDependencies": {
    "brunch": "^2.8.2",
    "css-brunch": "~2.0.0",
    "clean-css-brunch": "~2.0.0",
    "copycat-brunch": "^1.1.0",
    "sass-brunch": "^1.9.2",
    "javascript-brunch": "~2.0.0",
    "uglify-js-brunch": "~2.0.1",
    "node-bourbon": "^4.2.8",
    "bourbon-neat": "^1.8.0",
    "font-awesome": "^4.6.3",
    "turbolinks": "^5.0.0"
  "dependencies": {
    "babel-brunch": "^6.0.6"

All of the Brunch libraries are copied over from Phoenix's set up.

Here's the brunch-config.js

exports.config = {
	overrides: {
		production: {
			paths: {
				public: "build"
  // See for docs.
  files: {
    javascripts: {
      joinTo: "javascripts/all.js"
    stylesheets: {
      joinTo: "stylesheets/site.css",
      order: {
        after: ["source/stylesheets/site.css.scss"] // concat app.css last
    templates: {
      joinTo: "javascripts/all.js"

  conventions: {
    assets: /^(source\/assets)/

  paths: {
    // Dependencies and current project directories to watch
    watched: [

    // Where to compile files to
    public: ".tmp/dist"

  // Configure your plugins
  plugins: {
    babel: {
      // Do not use ES6 compiler in vendor code
      ignore: [/source\/vendor/],
			presets: ['es2015', 'es2016']
    sass: {
      debug: 'comments',
      options: {
        includePaths: [
        ], // tell sass-brunch where to look for files to @import
        precision: 8 // minimum precision required by bootstrap-sass
    copycat: {
      "fonts": ["node_modules/font-awesome/fonts"] 

  modules: {
    autoRequire: {
      "javascripts/all.js": ["source/javascripts/all"]
  npm: {
    enabled: true,
    whitelist: ["turbolinks"],
    globals: {
      $: 'jquery',
      jQuery: 'jquery'

In the overrides section you can see that the public directory is changed to build instead of .tmp/dist which is used in development. This is because when you run middleman build you'll want the files in the build directory and when you run middleman server you'll want them in .tmp/dist.

Watches are set to various asset directories to auto reload. You could also watch the whole source directory for changes if you so wish.

Copycat copies the Font Awesome font files to the appropriate directory

Javascript is set to allow for es2016 code so you can use various Javascript goodies in your code.

The only thing I can't get working is SASS include paths. Even though they are set here, Brunch refuses to find them when imported. This is easy enough to get around by including the relative path in the SASS files which I'll show in a moment.

Here's the relevant snippet of configuration for config.rb

activate :external_pipeline,
  name: :brunch,
  command: build? ? './node_modules/brunch/bin/brunch build --production --env production' : './node_modules/brunch/bin/brunch watch --stdin',
  source: ".tmp/dist",
  latency: 1

Here's how my SASS source/stylesheets/site.css.scss looks. Note that $icon-font-path is important for Font Awesome to find the fonts in the appropriate directory.

@charset "utf-8";
// @import "normalize";
$icon-font-path: "/fonts/";
$font-stack-system: "helvetica";
@import "../../node_modules/bourbon/app/assets/stylesheets/bourbon";
@import "../../node_modules/bourbon-neat/app/assets/stylesheets/neat-helpers";
@import "../../node_modules/bourbon-neat/app/assets/stylesheets/neat";
// @import "base/base"; // This is only for Bourbon Bitters
@import "../../node_modules/font-awesome/scss/font-awesome";

Bootstrap and Foundation can both be used in the exact same way as Bourbon. Just locate the main SASS file in your node_modules directory and import!

Example source/javascripts/all.js

import "turbolinks";

console.log('hello world :)');

There you have it! Have fun using Middleman and Brunch!

Spread the word

Share this article

Like this content?

Check out some of the apps that I've built!


Command-line snippet manager for power users



Third party app for iOS.



GUI for the rsync command