As a developer, I’m a huge fan of static websites. They are reliable, fast, and SEO-friendly. I also learned to love creating static websites by using tools like Middleman. In this post, I won’t try to convince you on why Middleman is great (maybe another day). Instead, I’ll be focusing on how to setup a Middleman 4 project that leverages best-practice front-end build tool and package management in tandem.
Before Middleman 4, using tools like Bower, Brunch, and Gulp always felt like more work than it was worth. Middleman was optimized for using Rails’ Sprockets to manage front-end assets and gems to handle dependencies (e.g. Sass, Babel, and React). The issue, however, was that many of these gems were infrequently updated and provided inconsistent API’s for integration with your project. If you’re familiar with front-end best practices, using tools like Bower to manage dependencies and Brunch (or Gulp, Broccoli, Webpack) for compilation should be a no-brainer. So how can we do that with Middleman?
Fear no more! In Middleman 4, the developer can choose to use an external build pipeline. Middleman makes no assumptions about what tools you prefer. Simpy tell it to activate the external pipeline, what command to run on server start, and where to look for the compiled assets. Could it really be that simple? Yep! Take a look at the actual code needed to set it up:
activate :external_pipeline, name: :brunch, command: build? ? 'npm run prod' : 'npm start', source: "./public", latency: 1
We tell Middleman that we’d like to use an external pipeline for our assets, use different build commands based on whether we’re building the project for production, and to look for the final output in the
public folder. In my case, they are
To add functionalities to Brunch, simply
npm install the corresponding packages. Here are the packages I’m using for this site:
So now that we have the necessary packages, how do we use them? Enter
brunch-config.js. This is the file Brunch looks for to figure out how to do its job. Here is the
brunch-config.js file I’m using for this site:
A bit overwhelming? No worries, I’ll walk you through the important bits.
pathskeys tells Brunch where to look for the source files so it knows to watch them for changes.
pluginskey enables and configures your Brunch plugins. In the case, I’m using Babel and Sass. The Sass plugin also allows you to include Sass files that are outside of your watched directories.
I won’t walk through every line of this file here. If you’re interested in learning more, take a look at the docs here. Brunch has a healthy plugin ecosystem as well–make sure to check out their plugins page.
Using Bower with Brunch
It specifies where to find the JS files (
./bower_components), and where to bundle them into (
vendor.js file, I can simply include it in my
layout.html.erb file in Middleman with
Brunch output path must match where we set the assets directories in
config.rb. For this site, I’ve set it to
Hence I have Brunch compiling all bundled files to the
That’s all you need! With this setup, we let the front-end build tool do its job so Middleman can focus on managing the site content. Remember that it really doesn’t matter what front-end build tools you use, the important thing is that it does what you need it to do. I’ve done a similar setup with Gulp before, which also worked out great. If you want to take a closer look at my setup, the source code is on GitHub.
I’m a big fan of Middleman and I plan to write more about it in the future. In the meantime, take a look at my SEO optimized Middleman template.
Got questions or feedback? Tweet me at @feifanw.