Webpack 2 and Middleman 4
A quick guide to using Webpack 2 with Middleman 4
I originally wrote this Nov. 29th, 2016 before Webpack 2 was out of beta, so I mostly re wrote it, including new gists, etc on Apr. 10th, 2017
As of version 4, Middleman now supports a variety of front-end/JS tooling via the External Pipeline, outlined here. Previously Middleman only built assets via Rails’ venerable Asset Pipeline aka Sprockets. There is a lot that could be said about Sprockets and why it may or may not be a good choice for Middleman going forward, but even the core Rails team is building in a way to integrate new JS tools like Webpack [edit as of 3/17], and its clear which way the wind is blowing. Having run a previous blog iteration and some clients’ sites on Middleman I’m pretty familiar with it, and I generally think the folks at thoughtbot have done a nice job. If I had more serious content management needs, I also like Jekyll a lot. Finally I use Webpack at work and think the people behind it are all mighty nice, so I decided to go that direction for the New & Shiny™ blog.
The example from the Middleman docs looked simple enough, it basically just
involved throwing the snippet below into the
activate :external_pipeline, name: :webpack, command: build? ? './node_modules/webpack/bin/webpack.js --bail' : './node_modules/webpack/bin/webpack.js --watch -d', source: ".tmp/dist", latency: 1
If you’re thinking to yourself, “surely it can’t be that simple” then you would
be correct. From there you still need to set up your
isn’t hard per se, but there’s a lot of room for frustration and errors. This is
doubly true if you aren’t a JS developer or are new to Webpack. I had a lot of
trouble setting up
extract-text-webpack-plugin and ultimately had to reach
out to the chronically delightful Sean Larkin
I also used a blog post by Ross Kaffenberger for reference. he uses Webpack 1, and his blog setup is worth
looking at in general. Here’s a like to his site’s github His
at the top level and looks a bit different than the one I’ll show below, as it’s
for a different version of Webpack, so don’t mix them up! I’m also using Yarn instead of npm, because I like the
So starting from the beginning, I’ll assume you have Ruby installed, and if not go here and make sure you have a working Ruby.
Install Middleman 4 and Start a Project
There are some simple instructions here,
but it pretty much boils down to running
gem install middleman. Once it’s done
installing you should be able to run
middleman init my_new_project and start a
new project. You will also need to install Node
and Yarn. If that all worked, congrats
you’re ready to go, and you may have broken the bubble on your bingo card.
cd my_new_project, and start a new yarn project:
Just use all of the defaults by hitting enter until it’s done, they should all be fine. Fore reference, here is what my demo repo looked like at this point. Next you’ll need to install a few packages.
yarn add --dev webpack [email protected]
This installs Webpack
yarn add --dev babel-loader babel-core babel-preset-es2015
and this adds Babel, a JS transpiler.
yarn add --dev css-loader extract-text-webpack-plugin sass-loader style-loader
Finally, this installs all of the things you need to do regular CSS and SASS.
Don’t forget to activate the
external_pipeline by adding the following to
activate :external_pipeline, name: :webpack, command: build? ? "./node_modules/webpack/bin/webpack.js --bail -p" : "./node_modules/webpack/bin/webpack.js --watch -d --progress --color", source: "build", latency: 1
You’ll notice this is a little different than the initial example, basically I’m just using a build directory and adding color to the Webpack output.
touch webpack.config.js and add the following:
Here is a raw gist for easy copying. Warning: opens new tab
The lines beginning with
test: /\.(sass|scss)$/, make the sass work, and these lines are basically straight from the
If you run
middleman, everything should basically work, and you should see
something like the following:
If that worked, you’re all set. If it didn’t go back and make sure all of your config and versions match. And for reference here is my repo at his point. Webpack may be overkill if you don’t do JS or if you only want to use vanilla JS and CSS, but if you want to use es6 or SASS, like me, then its probably worth the effort. If you’d like to see this blog’s source, it’s here on Github.
If you would like to learn more about Webpack, they have a great tutorial and docs.