Adding React to a Middleman project with Webpack

Middleman is a static site generator written in Ruby. It's a great way to produce rich static content sites without the need for a server. Despite this, it doesn't come with internal support for modern JavaScript frameworks like React. Luckily, Middleman 4 ships with a feature called External Pipeline which allows wiring in your own external build tool like Gulp or Webpack.

Let's look at how to integrate Webpack with Middleman for the purpose of using React on our site.

Install development dependencies

First, let's install the dependencies we'll need to build our React code. Note that we're using the --save-dev flag to indicate to npm that we should append these libraries to the devDependencies section of our package.json.

$ npm install --save-dev babel-core babel-loader babel-preset-es2015 babel-preset-react webpack uglifyjs-webpack-plugin
  • babel-core is the core Babel package for transpiling ES6 and JSX into browser-friendly ES5 JavaScript.
  • babel-loader is a Webpack loader which loads files from our path into Babel.
  • babel-preset-es2015 is a preset for Babel to transpile ES6 code.
  • babel-preset-react is a preset for Babel to transpile JSX code.
  • webpack is Webpack itself.
  • uglifyjs-webpack-plugin is a Webpack plugin to uglify and compress our code for production.

Install React

Next, install the React packages, this time using --save to indicate these are runtime dependencies:

$ npm install --save react react-dom

Set up your Babel configuration file

Babel has its own configuration file inside .babelrc. Create this file in the root of your Middleman project with the following contents:

  "presets": [
    "es2015", "react"

This file tells Babel to use the es2015 and react presets we installed in the first step.

Configure Webpack

Next we'll configure Webpack with a basic configuration file that supports both development and production environments. Place the following inside the file webpack.config.js in the root of your project:

// webpack.config.js
var webpack = require('webpack');

const isProduction = process.env.NODE_ENV === 'production';

const productionPlugins = [
  new webpack.DefinePlugin({
    'process.env.NODE_ENV': '"production"'
  isProduction ? new webpack.optimize.UglifyJsPlugin({
    compress: {
      warnings: false,
  }) : null,

module.exports = {
  entry: './assets/javascripts/index.js',
  devtool: isProduction ? false : 'source-map',
  output: {
    library: 'MyApp',
    path: __dirname + '/tmp/dist',
    filename: 'bundle.js',
  module: {
    loaders: [
        test: /\.js$/,
        loader: 'babel-loader',
        exclude: /node_modules/
  plugins: isProduction ? productionPlugins : []

Notice that we use the isProduction flag to toggle the use of the UglifyJsPlugin as well as whether we use a devtool to provide us with source maps for debugging.

Configure Middleman to build Webpack

Now that we've configured Webpack, let's tell Middleman to execute it whenever it rebuilds. To do this, we'll activate the external pipeline plugin in our config.rb and point it at the Webpack executable:

# config.rb

activate :external_pipeline,
  name: :webpack,
  command: build? ?
  "NODE_ENV=production ./node_modules/webpack/bin/webpack.js --bail -p" :
  "./node_modules/webpack/bin/webpack.js --watch -d --progress --color",
  source: "tmp/dist",
  latency: 1

When we run middleman build, we run Webpack with NODE_ENV=production. This triggers our production build options in our Webpack configuration.

When using middleman server though, we tell Webpack to --watch for changes and automatically rebuild.

Middleman will look for the result of our built assets inside tmp/dist. Let's go ahead and create that directory now:

$ mkdir -p tmp/dist

Build an example React component

Now that we've got our tooling configured, let's create a simple React component to test that everything works. First, create a directory to store your Webpack JavaScript assets. I place these files in assets/javascripts since Sprockets looks inside source/javascripts, and I don't want Sprockets to attempt to build my React code.

$ mkdir -p assets/javascripts

Next, let's sketch out a React component. Note that from index.js I'm exporting a function renderHello which renders the HelloWorld component to a DOM element specified by ID. This allows us to call upon fragments of React code from within existing pages.

// assets/javascripts/index.js

import React from 'react';
import ReactDOM from 'react-dom';

const HelloReact = props => (
  <div>Hello, React!</div>

function renderHello(id) {
  const el = document.getElementById(selector);
  ReactDOM.render(<HelloReact />, el);

export default {

Mount the component

Finally, mount the component onto an existing DOM element on a page. First include the built bundle.js file. Then, call renderHello:

    <div id="hello">

    <%= javascript_include_tag  "bundle" %>
    <script type="text/javascript">

Other resources

A notificationless life

I'm an anxious person.

Wait, strike that. I'm striving not to carelessly apply labels. I sometimes suffer from anxiety. There. That's better.

I sometimes suffer from anxiety. Having spent the majority of my waking adult life in front of a screen, I'm no stranger to the anxiety-inducing nature of life online in 2017. The average computer or smartphone user has hundreds of apps vying for their attention, each hoping to take a slice.

It didn't used to be this way. Before 2009 and the introduction of Apple's Push Notification Service, your iPhone left you alone except for when you received a phone call or a text message. Those were simpler times.

Now, if we don't do something about it, we're subject to a near-constant buzzing and chirping. Emails. Text messages. Tweets. Likes. It doesn't stop. As a technologist, I feel almost apologetic for the culture of distraction that is now our everyday reality.

That's why I want to do you a favor. I'm going to make a suggestion that hopefully will change your life for the better. Ready?

Turn off all your notifications.

That's right. Turn them all off. Even your text messages. Maybe leave your phone call notifications on so people can reach you in case of an emergency. But you haven't experienced the serenity the people of the twentieth century took for granted until you turn off all your smartphone notifications.

Afraid you'll miss something? You won't. If something is important enough, someone will call you.

Alias your common Ruby commands for a faster workflow

If you're a Rubyist, you probably use the likes of rspec, cucumber, rake, and other commands frequently. And it's likely that you might be running them using bundle exec to execute them in the context of your project's bundle. After finding I was spending a lot of time typing each of these commands, I added a few aliases to my shell config to speed up my workflow:

alias rsp='bundle exec rspec'
alias cuc='bundle exec cucumber'
alias rak='bundle exec rake'
alias mm='bundle exec middleman'

Paste these into your ~/.bashrc or ~/.zshrc, restart your shell, and now running an rspec test in the context of your bundle is as simple as:

rsp spec/models/banana_spec.rb

Have other useful aliases? Post them in the comments below!

A Jasmine matcher for Backbone.js Event Expectations

I wanted to be able to eloquently test Backbone.js event chains, so I wrote a custom matcher.

Adventures into Python

The office has been much more forgiving as of late and has given me more opportunities to learn different programming techniques. I have recently started learning wxPython, a Python GUI library based off wxWidgets. So far it has been an interesting experience and I’m really enjoying developing actual applications rather than mundane VBScript/SQL database web applications.

I’d like to start developing in Python more now that I’m more familiar with the syntax. It’s an excellent language once you get past the obscure syntax and can be quite efficient.

We’ll see what I come up with…