🚀 make things
📝 write about it

Webpack and GitHub Pages

Over the last year or so, GitHub Pages has become my favourite hosting platform. It’s free, it’s simple, and most importantly, it lets me get started building my random front-end ideas without first doing a big long back-end detour to set up a server and a deployment pipeline. Just create a repo and start pushing commits. You can’t beat it.

Only downside is, it can be a pain to combine with the likes of Webpack. The GitHub Pages configuration of Jekyll is understandably restrictive, meaning you have to build and commit the productionised version of your code before pushing. So the path of least resistance is to stick with plain old vanilla JavaScript, like people used to write way back in 2013. This sucks if you’d rather not have the Time Team people digging up your project before it’s even finished.

"Over at site B, the team have unearthed an early Bronze Age var statement"

There are lots of different ways around this problem. I’ve tried a few myself. I tried making the Jekyll dev server run Webpack every time it rebuilt the site, but that made rebuild times too long for coding to still be fun. I looked into running Webpack and Jekyll in parallel, but the logistics of that made my head spin. If you have a high tolerance for crappy tools you can probably just get used to doing a bunch of manual stuff to build every single code change but… 😩 no.

Anyway I reeeeeally wanted this. So bad. I wanted to be able to do random little JavaScript projects using all the modern shit, and deploy them to GitHub Pages, and do all that with a development workflow that doesn’t suck all the fun out of whatever I’m building. So I kept at it, and I’ve finally figured it out.

The sweet spot, in just the right place between all the nasty little trade-offs you have to make to do this, is actually really simple. When you’re working on your JS, you run the Webpack dev server. When you’re working on your HTML or CSS, you run the Jekyll dev server. There are a few subtle little quirks you have to get juuuuuuuust right on top of that, though. These are the secret ingredients that make it actually work. And I wanted to note them down here.

The main quirk is that before you start the Webpack dev server to work on your JS, you actually have to run a Jekyll build. And vice versa: before you run the Jekyll server to work on your HTML & CSS, you run a Webpack build. Try to just accept this without thinking about it too much. It’s easier that way. The trick here is to automate this out of the equation immediately. I set up a Makefile allowing me to run make webpack to run a Webpack dev server without remembering any of this crap.

You still have to compile and commit the production build of your app before pushing, though. The trick to avoiding a manual Webpack interaction before every push is to set up a pre-commit hook. Not only is this easy, it also builds on the existing automation from the Makefile.

make webpack-build
git add app.js

All this can be a right pain in the arse to get going. There’s always some fiddly little problem two thirds of the way through that eats up four hours of sheer misery. Maybe a Webpack error message whose only Google result is a single failed Travis CI build from 2009 (true story).

So I’ve made myself a blank, fully operational reference project to use as a jumping-off point. The source code’s there on GitHub, in case this sounds useful to anyone else. Mostly I’m noting all this down in such detail for my own benefit though, because I know I’m gonna forget some of this and will need to remember when part of it inevitably breaks.