Originally posted August 2014 at https://charliegleason.com

Harp, Gulp And BrowserSync

Or how I have a weird enthusiasm for static site generators

A couple of weeks ago I decided to rejig my personal site, because I hit a particularly tough patch in Saints Row 4 and what else would I spend a Saturday doing? Previously I’d had good experiences with Pith, which is a really solid Ruby based static site generator, but I’d overcomplicated the whole thing and it felt a bit clunky. Plus I wanted to try some new fanciness.

After setting up Jekyll, another Ruby based static site generator (we should acronym that, no?), I got a tweet from Glen Maddern, mentioning a deep affection for Harp.js. It made me realise that though I’ve admired it from afar, I hadn’t really messed much with Node.js, and a personal site is a pretty good place to get your hands dirty.

At the same time, I was hearing good things about Gulp.js, the Node based streaming build system, and I’d always found it’s predecessor Grunt.js a little verbose.

BrowserSync was the final piece of the puzzle, and I was primarily curious about its much touted ability to inject CSS changes without reloading the page.

So I dug in.

Setting it all up

So, we’ll need Gulp, Harp and BrowserSync.

Getting started with Gulp

The first thing I noticed, when checking out Gulp, was the simplicity. After wrestling with Grunt for so long, I was chuffed to see a single named function was all that’s needed to get started.

(To be fair, I’ve not written anything particularly onerous in Gulp, so that’s a bit harsh.)

First, make sure you’ve got Gulp installed.

npm install --global gulp

Then you’ll need a gulpfile.js at the root of your project.

var gulp = require('gulp');

gulp.task('default', function() {
  console.log("Gulp lol look at me being rad.");
});

As it’s the default task, just run gulp.

gulp

Getting started with Harp

Similarly, Harp is super straightforward.

sudo npm install -g harp

You can then use harp to generate the bones of a project.

harp init myproject

That will give you the barest of projects, using Less for styles and Jade for HTML. Personally, I prefer Sass and EJS, but it’s not hard to change things over. Harp tends towards convention over configuration, so all you really need is a single .ejs or .jade page and you’re good to go.

Getting started with BrowserSync

Finally, BrowserSync.

Technically you don’t need to install this globally, unless you’re using it separately from the command line, so you can skip this step and just have it in your npm package.json.

But, if you’re keen:

npm install -g browser-sync

For this example we’ll run BrowserSync via Gulp, so you don’t need to do anything else at this point. You can run from the command line though, using the browser-sync command.

Setting the scene

So, there are some dependencies involved. To make life a little easier, I’ve pulled together the cleverly titled boilerplate, harp-gulp-browsersync-boilerplate. You can use it to get the whole thing up and running straight away, and then I’ll go through and explain what’s happening. Cool? Cool.

Let’s take a moment to look at a lolcat.

Phew.

That was awesome.

So, Harp has a really great feature where you can use any repo as a boilerplate. To use my super-fancy repo, you just need the --boilerplate (or -b) option.

harp init src --boilerplate superhighfives/harp-gulp-browsersync-boilerplate

Then, once it’s downloaded (maybe make a tea or something?) you can jump into src and grab the dependencies.

npm install

Maybe make another tea? You may be sick of tea by now. I’m not confident in how much tea you drink each day, so I don’t want to be presumptious.

Finally, run gulp.

An example of the terminal output you should probably see.

Here’s what is happening. Gulp fires up Harp on port 9000 (you can change that in the gulpfile.js), and BrowserSync proxies it, usually on 3000. So just hit up localhost:3000 and you’re ready to party. It’s worth checking the output in your terminal though, as it will give you the definitive address.

Changing things, because you can

Now you can edit main.scss and the updates will happen in real-time. It’s the same system that’s currently running this blog, and you can see the full range of tasks (including deploying straight to Github Pages) in the source over on Github.

This is the sound of you succeeding, you beautiful human.

Acknowledgements: Glen Maddern cracked the BrowserSync injection, and is just the best human