Lysterfield Lake

Machine learning, art, accelerometers, and the joy of slow progress and fast feedback loops (or, how I built Lysterfield Lake)

⚠️ You can see a new (updated, mobile, and dark-mode friendly) version of this case study at charliegleason.com/work/lysterfield-lake

Lysterfield Lake is a song about a place outside Melbourne, Australia. It’s about the endless summers of your youth, and the tiny changes in you that you don’t even notice adding up. It’s also about memories, which, like polaroids, fade and change over time.

I don’t remember exactly when I wrote it in much the same way I don’t remember exactly when I started this project, which has spanned the better part of a year and has all but consumed the most creative bits of my brain.

I think it all began when I came across Replicate (and by extention, their open-source container for running machine learning models, Cog.) I was so inspired by their Explore page, and, if I’m being totally honest, I was worried about the cost of experimenting with AI. I’d set up a gaming PC in the weird limbo of the 2020 lockdowns, and these tools made it effortless (and for the most part, free) to try, and test, and many, many times, fail.

When I decided to release new music (it’s been seven years since the last Brightly record) I knew I wanted to build something with these bits and pieces I’d been noodling with. I knew I wasn’t great at making traditional music videos, and I felt empowered by the flexibility of the browsers, and the creative opportunties afforded by using machine learning and AI. I think the result is something greater than the sum of its parts.

And there are a lot of parts.

(Also, if you haven’t seen the video, you should go and check it out before I ruin the magic by shining a very bright light on exactly how it all works.)

(And if you’d rather check out a recording, you can jump over to YouTube to see a simplified version that should give you a pretty good idea.)

What is it?

Lysterfield Lake is a 3D generative interactive music video. It works in the browser, using Three.js and react-three-fiber to stitch together seven feeds of video frame by frame, turning a single piece of footage shot on an iPhone into a three-dimensional fever dream. It uses the accelerometer in your phone, if it’s available, or your mouse if you’re on a computer. It shows and hides the protagonist as you watch depending on your actions, offering a myriad of ways to experience it. New dreams can be added at any time.

Behind the scenes it was modelled in Blender, (using a polaroid model by Edoardo Galati), generated in python and shell scripts, and built in JavaScript. It is made up of entirely open-source projects that are freely available.

The process

So, how does it work? I made a diagram to help.

First, a single video file, shot on an iPhone, is fed through a series of python and shell scripts. The initial one splits the video into individual frames. These frames then go through a bunch of processes depending on their final output.

The Avatar

A 3D-watercolour version of the subject matter (which is, in this case, me).

• DiffusionCLIP turns the image into a painted watercolour style.
• RobustVideoMatting finds the subject in the video and creates an alpha mask of it.
• In python, the mask is used with the original image and passed to ZoeDepth, which creates a depth mask.
• These three elements (the watercolour image, the alpha mask, and the depth mask) are used to render the avatar.

The Background

A watercolour version of the original image, without the subject matter.

• Using the alpha mask and the original image, Inpaint Anything creates a version of the scene without the avatar in it.
• This inpainted image is then also painted in watercolour using DiffusionCLIP.
• This element is then used to render the background.

The Outline

A comic-book style sketch of the subject matter.

• In python, the original image is combined with the alpha mask to create a version with no background.
• This is then fed into artline-torch, which creates a rough outline sketch.
• This sketch is then overlaid on the avatar during rendering (it also uses a bit of dithering in the custom shader in Three.js, which is what gives it the printed ink / slight comic book style).

The Dreams

Prompt-generated reinterpretations of the original image.

• The original images are fed into Deforum Stable Diffusion, along with a prompt, creating unique scenes that mirror the subject matter. For example, trees and a lake that match the contours of the image.

• Finally, each frame is manually reviewed one by one and removed if not appropriate. (The primary reason for this is that Stable Diffusion models are trained on image sets that include a large amount of waifu’s. Which, because the input clearly contains the shape of a person, means a lot of waifu’s end up in the output, even when politely asking Stable Diffusion not to.)

• The remaining images are fed into rife-ncnn-vulkan, which interpolates the missing frames and generates new ones to fill the gaps.

The Lyrics

(Apologies for my handwriting. I clearly should’ve been a doctor.)

At the same time, I recorded myself hand writing the lyrics in Procreate, and then cleaned them up in Adobe’s After Effects.

The output

An ultra-wide for each dream.

This gets stitched together into an ultra-wide video with 7 square images side-by-side. Originally I tried using a single video for each element, but it‘s impossible to guarantee frame sync across multiple videos in the browser. Fortunately, much like how there’s no rule against eating a candy bar on a dance floor, there’s no rule that videos need to be 16x9. Using custom shaders in the browser, you can simply grab the crop of footage you need for each element in real time.

And having all of these elements in the one shader affords new opportunities. By passing the depth mask, alpha mask, and the watercolour scene, I was able to generate a rough 3D model.

Custom shaders essentially let you paint with pixels in real time, and it’s an incredibly exciting medium once you start to explore the possibilities. It is how I can use the pixels from the depth mask to directly impact how close or far each fragment of the 3D avatar is. And, if you’d like to learn more, The Book of Shaders is a great resource.

Each frame of each video includes the handwritten lyrics, the watercolour scene, the watercolour scene with the background removed, the alpha mask, the depth mask, the sketch, and the dream. And those ultra-wide videos form the backbone of the project.

The conclusion

The selected dream, represented by one of these videos, is then chopped up and stitched back together in real time in the browser, using react-three-fiber, and many of the incredible resources provided as part of the drei project. You can explore each dream one by one, wandering through a landscape that has been imagined by a computer, listening to a song about a time that sits on the very edge of my conciousness. Memory, like AI, is funny like that.

This is a probably a good time to mention that, while this is the conclusion, this project took every possible detour, hit every possible technical hitch, and explored every possible weird twist and turn. What I’ve ended up with is absolutely nothing like what I imagined, because I didn’t really know what I was going to get at the end. Which makes it a sort-of love letter to the creative process, and to the joys of pursing something purely for the “what-if” of it. There are so many ways that sticking with something can truly surprise you, and that doesn’t have to involve making weird music videos — it could be baking, or cross stitch, or learning a language, or dance. Things you can experiment with, be creative with, grow with. Things that make you feel like you did something you previously couldn’t. Maybe even something great. That might be the greatest feeling there is.

I hope you find it inspiring, or at the very least, mildly interesting, and I appreciate you taking the time to learn more about how the project works.

Okay, how do I find out more?

🎨 📸

If you’d like to check it out, you can do so here:
https://lysterfieldlake.com/

The project itself is entirely open-source, and available at the following GitHub repositories:

superhighfives/lysterfield-lake

A React app, powered by React and react-three-fiber.

superhighfives/lysterfield-lake-pipeline

The pipeline that generates the video used by the app, powered by python and shell-scripts.

Author’s note: Fair warning—it’s not the cleanest code, and in the case of the pipeline, it’s not something that will work locally out of the box. I definitely intended open-sourcing this to be educational, in the sense of “oh, that’s how he did that!”, as opposed to aspirational, like “oh, that’s how he thinks React should be written??” It was a passion project, so maybe bear that in mind. Cheers. 😅

🎵 🥁

If you’d like to check out my music, you can find Brightly here:
https://wearebrightly.com/

💌 🥰

If you’d like to share this project, that would be greatly appreciated.

🙏 👏

Thanks to all my mates who came on country walks while I filmed myself awkwardly mouthing along to my own music. To Ian and Georgia for filming the real thing in Scotland. And to everyone who told me I’m not too old to keep making things.

Also, this project wouldn’t have happened, like all my projects, without the support and encouragement of Glen Maddern. ❤️

Produced and Mixed by James Seymour in Naarm.
Mastered by Andrei “Ony” Eremin in Philadelphia.

Thank you for listening.
@wearebrightly / wearebrightly.com

Lysterfield Lake — An AI Experiment was originally published in superhighfives on Medium, where people are continuing the conversation by highlighting and responding to this story.

A free, open-source colour picker app for macOS

Pika (pronounced pi·kuh, like picker) is an easy to use, open-source, native colour picker for macOS. Pika makes it simple to quickly find colours onscreen, in the format you need, so you can get on with being a speedy, successful designer.

It was designed and built from the ground up as a love letter to macOS, by a designer, for designers. In that spirit, the source code is freely available, as is the app, and I would love for more people to get involved in its roadmap and its future.

The TL;DR:

• You can check Pika out at superhighfives.com/pika.
• The source code is available on GitHub. Contributions are welcomed and encouraged. I have a laundry list of stuff I’d love to do in the project roadmap, and you can create issues, or open your own PR. The world is your oyster.
• The core code licence is MIT, while all libraries and third-party extensions have their own licences, which are flagged in each.
• I’d love to hear your feedback, and your contributions. The easiest way is to open a feature request on GitHub.

The Longer Story

I’ve always wanted to develop for macOS.

I got my first iMac (the ridiculous, and ridiculously great, G4 lamp) when I started university, and coming from Windows I grew a real affection for the craftspersonship of Mac apps. I loved the attention to detail, and the way the operating system seemed really connected–you could easily add the rad emo song you were listening to in iTunes to a LiveJournal post you were writing in another app. It felt effortless, and magic.

Since then, I’ve wanted to craft something that made people feel how that felt. But every time I tried to start learning, I’d download XCode, open it up, and come unstuck. Objective-C has always felt wildly verbose to me, and when I got the urge to dip yet another toe in the water I’d end up wrestling with certificate signing until I gave up, deflated.

Then, in 2014, Swift was announced, and it promised to be the answer to all of my questions. A new syntax, with modern features, and an excited new community. In 2019, the declarative SwiftUI framework followed, as did opportunities to share code between macOS, iOS, tvOS, and watchOS. Suddenly all I needed was a genuinely horrifying pandemic to justify not leaving my study for a couple of weeks, and I was all set to fulfil my lifelong dream.

As tends to be the case, it ended up leading me down an endless warren of endless warrens of rabbit holes, which included (but was not limited to):

• Diving deep into the Apple ecosystem, its history, and the many, many different frameworks and APIs (from UIKit to AppKit to Cocoa to SwiftUI).
• Writing some very questionable, and then hopefully slightly less questionable, Swift code.
• Designing and building a NextJS-powered marketing site, at superhighfives.com/pika, enchanced with WebGL and GSAP.
• Constructing a toolchain to support the Sparkle release framework, generating XML via markdown.
• Creating a custom shader in WebGL, and porting it to Apple’s (very cool) Metal framework.
• Refactoring things an absurd number of times. Just an absurd number.
• And, because I couldn’t help myself, designing and developing a brand, with its own colour scheme, typography, iconography, and look and feel.

But, even with all that, it was an absolute blast.

I genuinely sweated every single pixel of it, and while there’s much more to do (and some wild SwiftUI features / bugs to dig deeper into) hopefully that effort shows. I’m incredibly excited about the future of Swift and SwiftUI, and I don’t think there’s been a better time to dip your toe in.

In that spirit, I’d love it if you’d take the time to check out Pika, and to contribute to its future, so we can collectively keep this love letter going.

PS: You can check out more of my work at charliegleason.com,or explore more helpful apps and libraries at superhighfives.com.

Introducing Pika was originally published in superhighfives on Medium, where people are continuing the conversation by highlighting and responding to this story.

Using create-react-app, react-router, and zero configuration

Quick tip—if you’ve built something fancy with create-react-app and react-router and you’re not doing any server side stuff (as in, it’s all on the client side), you can get Surge to automatically catch and pass requests to your app. All you need to do is duplicate your index.html after the build step, naming it 200.html.

You can see this in action here. Without the 200.html, visiting /lyrics would result in a 404:
https://stretchurskin.com/lyrics

Surge’s 200.html file is a fallback, like the 404.html file, but for single page apps and client-side routing. —Surge docs

With create-react-app it’s as easy as amending your build step in your package.json:

"build": "react-scripts build && cp build/index.html build/200.html"

And deploying:

surge build

And then celebrating, because you are a success. 💖

👌 Zero Config Client Side Routing With Surge.sh was originally published in superhighfives on Medium, where people are continuing the conversation by highlighting and responding to this story.

Blending a rock-solid API and CMS with the absolute best in front-end tooling, built as a single project and hosted seamlessly on Heroku.

Update, 16 May 2018: First off, thank you to everyone who has taken the time to give feedback, share their experiments, and clap this post. Since I finished this last year I joined Heroku, and with their help I’ve rewritten it to iron out the bugs, implement your feedback, and to include support for Rails 5.2.0, React Router, and Yarn.

You can find version 2.0 of this post here: https://blog.heroku.com/a-rock-solid-modern-web-stack

You can also find latest repo, including a Heroku button you can automagically deploy with, here: https://github.com/heroku/list-of-ingredients

Once again, I could not be more appreciative of your support and feedback.

Rails is an incredible framework, but sometimes you don’t need all the bulk of the asset pipeline and a layout system. In Rails 5 you can now create an API-only Rails app, meaning you can build your front-end however you like. It’s no longer 100% omakase.

Like using create-react-app, for example.

And for projects that don’t need CMS-like capabilities, that works pretty great straight away. create-react-app even supports proxying API requests in development, so you can be running two servers locally without having to do any if NODE_ENV === ‘development’ voodoo. Gosh, create-react-app is great.

Still, I’ve worked with ActiveAdmin on a few projects, and as an interface between you and the database, it’s pretty unmatched for ease of use. There are a host of customisation options, and it’s super easy for clients to use if you need a CMS.

The issue is that removing the non-API bits of Rails breaks it. Not ideal. But never fear, all is not lost! With a couple of steps you can be running a Rails 5, API-only, serving your create-react-app client on the front end, with full access to ActiveAdmin.

We’re going to build it, then we’re going to deploy it to Heroku, and then we’re going to celebrate with a drink. Because we will have earned it. Given that theme, we’re going to build an app that shows us recipes for delicious drinks. It’s thematically appropriate!

So, what are we going to use?

• Create React App
  All the power of a highly-tuned Webpack config without the hassle.
• Rails in API-only mode
  Just the best bits, leaving React to handle the UI.
• ActiveAdmin
  An instant CMS backend.
• Seamless deployment on Heroku
  Same-origin (so no CORS complications) with build steps to manage both Node and Ruby.

And it’ll look something like this:

If you want to skip ahead to the finished repo, you can do so here:
https://github.com/superhighfives/list-of-ingredients

And if you want to see it in action, you do that here:
https://list-of-ingredients.herokuapp.com/

Let’s get started, shall we?

Step 1: Getting Rails 5 set up

With that delicious low-carb API-only mode

There are a ton of great tutorials on getting Ruby and Rails set up in your local development environment. https://gorails.com/setup/ will work out your operating system, and will walk you through getting Rails 5.0.1 installed.

If you’ve already got Rails 5, awesome. The best way to check that is to run rails -v in your terminal. If you see Rails 5.0.1, we’re ready to roll.

Note: At the time of writing the newest version of Rails, 5.1, doesn’t quite work with these steps. Best to stick with 5.0.1 for now.

So, first up, start a new Rails app with the --api flag:

mkdir list-of-ingredients
cd list-of-ingredients
rails new . --api

Right. We are already part of the way to making a delicious cocktail. Maybe use this time to congratulate yourself, because you’re doing great.

Once the install process has finished, you can fire up Rails:

bin/rails s -p 3001

It’ll do some stuff, eventually telling you that it’s listening on http://localhost:3001. If you visit it, you should see something like this:

There’s even a kitten! So great.

Step 2: Getting ActiveAdmin working

With a couple of small tweaks to Rails

(Thanks to Roman Rott for this bit.)

So, incredibly (and awesomely, which is not a word), you can still get ActiveAdmin working like a charm with this set up. Before you can install it, you just need to switch a couple of Rails classes and add some middleware that ActiveAdmin relies on.

First, you’ll need to swap your application_controller.rb from using the API to using Base:

As Carlos Ramirez mentions, this requirement is an unfortunate design decision from ActiveAdmin, as now any controllers we make that inherit from ApplicationController won’t take advantage of the slimmed down API version.

There is a work around, though. Add a new api_controller.rb to your app/controllers:

So you can get your controllers to inherit from ApiController, not ApplicationController. For example:

From there we’ll need to ensure that the middleware has the stuff it needs for ActiveAdmin to function correctly. API mode strips out cookies and the flash, but we can 100% put them back. In your config/application.rb add these to the Application class:

Your config/application.rb should look something like this:

Do not confuse the flash with The Flash, who is likely heavily trademarked. I don’t have the kind of money I’d need laying around if he turns out to be litigious.

You should also move gem 'sqlite3' into the :development, :test group and add gem 'pg' into the :production group. Heroku doesn’t support sqlite, and you’ll need to swap those things around once you get to deploying your app. Why not do it now?

Now, keen developers will be sharpening their pitchforks right now, because you should 100% run Postgres locally if you’re developing a Real Application, to ensure your local environment matches your production one. But for the purposes of this exercise, let’s just be roguish and tell no one. They’ll never know.

Bundle and install everything, and then install ActiveAdmin:

bundle install
bin/rails g active_admin:install

You should see something like the following:

Finally, migrate and seed the database:

bin/rake db:migrate
bin/rake db:seed

Once again you can fire up Rails:

bin/rails s -p 3001

But this time hit http://localhost:3001/admin. You should see something like this:

And you should take a moment to feel pretty great, because that was a lot.

You can log into ActiveAdmin with the username admin@example.com and the password password. Security! You can change it really easily in the rad ActiveAdmin environment, though, so fear not.

Step 3: Adding create-react-app as the client

Yay! Super-speedy Webpack asset handing!

(Shout out to Full Stack React for this bit.)

So. We need a front end. If you don’t have create-react-app yet, install it globally with:

npm install create-react-app -g

And then, in the root of your app, generate it into the /client folder:

npm install -g create-react-app
create-react-app client

It’ll take a bit. You probably have time for a cup of tea, if you’re feeling thirsty.

Once it’s installed, jump in and fire it up:

cd client
npm start

Right! You have a simple create-react-app running. That is good. But we can do more than that.

As I mentioned earlier, one of the best bits about working with create-react-app and an API is that you can automatically proxy the API calls via the right port, without needing to swap anything between development and production. To do this, jump into your client/package.json and add a proxy property, like so:

"proxy": "http://localhost:3001"

Your client/package.json file will look like this:

(You might wonder why we’re proxying port 3001. Once we hook everything up our scripts will be running the API on port 3001, which is why we’ve been running Rails that way. Nice one picking up on that, though, eagle-eyes. Asking the right questions!)

fetch (along with a bunch of fancy new language features and polyfills you should 100% check out) is included with create-react-app, so our front end is ready to make calls to the API. But right now that would be pretty pointless—we’ll need some data to actually fetch.

So, let’s get this cocktail party started. We’ll need two relations, the Drinks, and the Ingredients that those drinks are made with. You’ll also potentially need a blender, but honestly, a margarita with a couple of ice cubes is still so delicious. Promise.

Now, normally I’d say avoid scaffolding in Rails, because you end up with a ton of boilerplate code that you have to delete, but for the purposes of the exercise, let’s use it. And then delete it. Do what I say, not what I do and all that.

Before that though, I should mention something. One downside to ActiveAdmin using inherited_resources, which reduces the boilerplate for Rails controllers, is that Rails then uses it when you scaffold anything in your app. That breaks stuff:

Fortunately, this is a solvable problem. You just need to tell Rails to use the regular scaffolding process. You know, from when we were young and scrappy and people didn’t say JavaScript fatigue like having options is a bad thing. The Good Old Days.

Just remind Rails which scaffold_controller to use in your config/application.rb and we can be on our way:

config.app_generators.scaffold_controller = :scaffold_controller

Your application.rb should look something like this, and everything should be right with the world again:

Crisis averted!

So, scaffolding. First, the Drink model:

bin/rails g scaffold Drink title:string description:string steps:string source:string

Then, the Ingredient model:

bin/rails g scaffold Ingredient drink:references description:string

Notice that the Ingredient references the Drink. This tells the Ingredient model to belong_to the Drink, which is part of the whole has_many relative database association thing.

See, my Relational Databases 101 comp-sci class was totally worth it.

Unfortunately this won’t tell your Drink model to has_many of the Ingredient model, so you’ll also need to add that to app/models/drink.rb all by yourself:

Then we can migrate and tell ActiveAdmin about our new friends:

bin/rake db:migrate
bin/rails generate active_admin:resource Drink
bin/rails generate active_admin:resource Ingredient

Go team.

Now, Rails is a security conscious beast, so you’ll need to add some stuff to the two files ActiveAdmin will have generated, app/admin/drink.rb and app/admin/ingredient.rb. Specifically, you’ll need to permit ActiveAdmin to change your model, which when you think about it is pretty important.

First up, app/admin/drink.rb:

Then app/admin/ingredient.rb:

Without permit_params, you can never edit your delicious drink recipes. Not on my watch.

In our routes, we’ll need to hook up the drinks resource. I like to scope my API calls to /api, so let’s do that:

Start the server:

bin/rails s -p 3001

And you should be able to visit http://localhost:3001/api/drinks to see… *drumroll*

{
}

Nothing. We should probably add some drinks. To save some time, here’s a db/seeds.rb that I prepared earlier, featuring a delicious negroni and a delicious margarita:

You’ve already migrated, so it’s just a case of seeding the database:

bin/rake db:seed

Now when you refresh you should see:

So, we’re pretty much good to go on the database front. Let’s just massage our scaffolded controllers a little. First, let’s cut back the DrinksController. We can make sure def index only returns the id and title of each drink, and we can make sure def show includes the id and description of each ingredient of the drink. Given how little data is being sent back, you could just grab everything from index, but for the purposes of showing how this could work in the Real World, let’s do it this way.

You’ll want to make sure your controllers are inheriting from ApiController, too.

And let’s just get rid of 99% of ingredients_controller.rb, because it’s not going to be doing a lot:

And now we have some fancy data to feed the client. Good for us! This is a big chunk of the setup, and you’re doing great. Let’s celebrate with some Adventure Time, and take this opportunity to think about how great that cocktail is going to be. Talk about earning it:

Next up, let’s create a Procfile in the root of the app for running the whole Rails / create-react-app setup locally, because Heroku uses procfiles to manage your bundle. If you haven’t used them before, you can read about them here.

We’ll call it Procfile.dev, because while we do need to run a Node server locally we’ll be deploying a pre-built bundle to Heroku, and we won’t need to run a Node server as well. Having a Node server and Rails server locally massively speeds up development time, and it is pretty great, but it’s overkill for production. Your Procfile.dev should look like this:

Procfiles are managed by foreman, which if you don’t have installed you can add with:

gem install foreman

And you can fire up the new set up with:

foreman start -f Procfile.dev

Who wants to type that every single time though? Why not make some rake tasks to manage running development and production locally for you? Just add start.rake to your /lib/tasks folder:

You’ll also need to add Foreman to your Gemfile (I’d recommend putting it in your :development group:

Then install it:

bundle install

And from there all you need to do to fire up your development environment is run the super simple:

bin/rake start

Glorious! Ten keystrokes to fire up two servers? What magic is this?!

And to test production (which will take a while to build without a great deal of output):

bin/rake start:production

Well, that step was a lot. So what’s happening here?

foreman will start the front end, /client, on port 3000 and the API on port 3001. It’ll then open the client, http://localhost:3000 in your browser. You can access ActiveAdmin via the API, at http://localhost:3001/admin, just like you’ve been doing all along.

Now we can sort our the React app. The simplest thing is to just check it works:

In your console, you should see the API call logged:

Which we can 100% use to grab the actual details of each fine beverage from drinks#show in Rails. Sure, we could’ve just sent everything from the server because it’s only two drinks, but I figure this is closer to how you’d really build something, so let’s go with it.

Now, rather than go through the full front end application, you can either grab the client folder from the repo:

http://github.com/superhighfives/list-of-ingredients

Or you can install the following dependencies:

npm install semantic-ui-react --save
npm install semantic-ui-css --save

And add them to your /client app. First, add the css to client/src/index.js:

And the all the fancy bells and whistles to your client/src/app.js:

Either way you choose to do it, you’re golden!

You should have a fancy front end that uses Semantic UI and looks something like this:

Step 4: Get everything ready for production

With Rails serving the Webpack bundle

So, how do we get our Rails app serving the Webpack bundle in production?

That’s where the magic of NPM’s package.json‘s postinstall comes in. We can get Heroku to build the app on the server, and copy the files into the /public directory to be served by Rails. We end up running a single Rails server managing our front end and back. It’s win win! There are a couple of steps to make that happen.

First up, let’s make a package.json file in the root of the app, which tells Heroku to compile the create-react-app. The postinstall command will get run after the node build is (you guessed it) installed. First up it’ll build it, then it’ll move the files into /public. How easy is that?

As always, you are doing great. Also, honestly, my hands are getting sore. On the plus side, this step is super short! Go team!

Step 5: Deploy it to Heroku

And celebrate, because you’ve earned it

We are super close! Soon, everything the light touches will be yours, including a fresh, tasty beverage. So let’s create a new Heroku app and get this thing over the finish line:

heroku apps:create

Now, if you push to Heroku, this looks like a dual Rails / Node app. But your Node code needs to be executed first so it can be served by Rails. This is where Heroku’s buildpacks come in — they transform your deployed code to run on Heroku. We can tell Heroku, via the terminal, to use two buildpacks (or build processes) in a specific order. First nodejs, to manage the front end build, and then ruby, to run Rails:

Let’s make a Procfile, in the root, for production, which will tell Heroku to run the Rails app:

Before we deploy it’s worth noting that create-react-app defines react-scripts, which manages the build of the client (along with a bunch of other stuff), as a devDependency in your package.json. Heroku sets an ENV var, NPM_CONFIG_PRODUCTION, to true, which means your build will disregard any devDependencies and it will fail. Not ideal.

But not unfixable! To overcome this you have two options. You can either set NPM_CONFIG_PRODUCTION to false:

heroku config:set NPM_CONFIG_PRODUCTION=false

Or you’ll need to move the react-scripts in your /client/package.json out of devDependencies into dependencies:

Both options will work, but given that you’ll likely have more than one devDependency, it’s easier to tell Heroku to recognise them. Normally I’d say you should always tune your production environment for, well, production, but in this case we’re building the assets with Node, not serving them.

With that sorted, we can deploy this beautiful beverage-based beast:

git add .
git commit -vam "Initial commit"
git push heroku master

Heroku will, following the order of the buildpacks, build the client, and then fire up Rails.

You’ll need to migrate and seed your database on Heroku, or ActiveAdmin will not be thrilled (and you won’t be able to log in). That’s easy enough though:

heroku run rake db:migrate
heroku run rake db:seed

And there you have it:

When you visit your app you’ll see the create-react-app on the client side, displaying some delicious drink recipes. You’ll also be able hit /admin (for example, https://list-of-ingredients.herokuapp.com/admin) and access your database using that truly terrible username and password ActiveAdmin chose for you. I’d recommend changing those on production ASAP. I did, so you can’t just change all my demo recipes to be really rude. I’m gutted you’d even try to, honestly, after everything we’ve been through.

It’s worth noting, if you’re planning to use react-router from here, there’s a few more steps you’ll need to take. Logan asked about it, so thanks Logan!

This isn’t exactly the most thrilling demo (especially given it suggests putting prosecco in a negroni, which is a capital crime in some parts of the world) but hopefully it gets you up and running. All the ingredients to make a delicious Rails API / Activeadmin / create-react-app beverage are here, and the sky’s the limit.

You can see a ready-to-go repo here, too:
http://github.com/superhighfives/list-of-ingredients

Thanks for taking the time to have a look, and I genuinely hope you celebrated with a drink, alcoholic or otherwise. 🍹

Shout out to Roman Rott and Full Stack React for the inspiration to put this together. And a massive thank you to Glen and Xander for taking the time to make suggestions and proofread this small essay for me. 💖

If you have any questions leave a comment or say hi via Twitter. Alternatively, enjoy a GIF of a dog wearing a hat.

A Top Shelf Web Stack—Rails 5 API + ActiveAdmin + Create React App was originally published in superhighfives on Medium, where people are continuing the conversation by highlighting and responding to this story.

A playground for creative coding using JavaScript and the canvas element.

I’ve long been fascinated with blurring the line between art and technology, and there are few places where exploring it is more easily achievable, or enjoyable, than the web. Browsers have come a long way since the heady days of IE6, and building complex visualisations and / or GPU-powered looping cat gifs is just a few tutorials away.

My experiments, over time, have relied more and more on the <canvas> tag. The wealth of incredible tools and resources available to manipulate this seemingly innocuous DOM element seem limitless, and I built Sandpit as a love letter to them.

🤓 So, what is it?

At its heart, Sandpit is a library that helps simplify creative coding. It does what it can to help, and gets out of the way when it can’t. Because you always have access to the <canvas> object, and to its context, you only have to use Sandpit when it benefits you. It looks like this:

const sandpit = new Sandpit('body', Sandpit.CANVAS)

The key features of Sandpit:

• Custom settings are easy to automagically configure, and then manipulate, with dat.GUI. For example, the following will give you a colour picker with red as a default:

sandpit.settings = {strokeColor: {value: 'red', color: true}}
console.log(sandpit.settings.strokeColor) // 'red'

• The current state is stored in the query string, making it simple to copy and paste your exact configuration to anyone who’s got the same settings as you—like in a staging environment, or locally. Tweak it, then paste it in Slack (👍, says your friend / client / co-worker).
• The animation loop is ready to go via sandpit.loop(), without needing you to write a single requestAnimationFrame.
• Inputs are normalised, from mouse to touch to gyroscope data, and there are event hooks, like sandpit.move(), to access them.
• Support for 2D or 3D canvases — it plays nice with libraries like Three.js, too, in case you just want simple access to touch inputs or the animation loop.
• Canvas resizing is automatically handled, with a preference towards setting and respecting the size in CSS (and a hook to override that).
• A bunch of related tools and libraries that are simple to access, including maths helpers, Color, and Victor.
• A growing suite of demos and documentation, and support for ES6, ES5, and the <script> tag.

👏 Why use it?

Good question. There are a number of tools that exist already that you should absolutely check out, but Sandpit offers a bunch of unique features, easy to use demos, examples and documentation at https://sandpitjs.com. That said, I’ve made a list of tools worth considering, because due diligence is a Very Good Thing.

I’d love you to try Sandpit (you can start playing with the demos here), suggest features by opening an issue, and generally let me know what you think. And if you wanna skip the setup and get straight to building stuff, fork this Codepen and check out the documentation.

Oh, and 100% comment with your experiments so I can tell you how great they are, you superhero. ✨

sandpit.start()

⛱ Sandpit: https://sandpitjs.com
⚡ Github: https://github.com/sandpit/sandpit
😍 Examples: https://github.com/sandpit/sandpit-site

Announcing ⛱ Sandpit was originally published in superhighfives on Medium, where people are continuing the conversation by highlighting and responding to this story.

Or how create-react-app, with a couple of modern tools, can make building static sites (with benefits) a breeze.

Update, 11 December 2017: The response to this setup has been super cool. My sincere thanks to those who have helped people get set up in the responses, and to those who have reached out with advice and high fives.

I have updated the dependencies in the repo to the latest versions, along with the guide, and tested that everything is still working as expected. Some of the output in your terminal might look slightly different than the screengrabs, but do not fear—you’re all good! Also, stereobooster has put together an amazing overview of possible performance optimisations for the final product which is well worth a read.

And again, thanks for reading.

Charlie Gleason on Twitter

Speaking of, react-helmet + react-snapshot + react-router = instant joy. Note to self: write blog post / love letter.

I’m a big fan of create-react-app. It hugely simplifies starting a new React-based project, and it serves pretty well for any ES6 / ES2015 setup regardless of whether you use React. I originally built Sandpit with it, purely because I could get straight to coding, writing tests, and deploying to a static site host like Surge or Now.

create-react-app’s best feature is its simplicity, but that that simplicity comes at a cost. As your application grows in complexity, you either have to yarn eject and take the entire set up into your own hands, or live with the limitations.

But hey, neither of those options are necessarily bad. But if you’d rather stick within create-react-app, there are a few tools you can use to take advantage of the incredible ease of use and speed of development that comes with create-react-app, without any terrifyingly massive webpack.config.js files keeping you up at night.

So, what are they?

There are five ingredients to this delicious paella of web development joy.

create-react-app
Kind of goes without saying, really.

react-router
Declarative routing for React, with a fancy new v4 that resolves a lot of the confusion around using the library.

react-helmet
Manages the document head, including title, description and meta tags.

react-snapshot
A zero-configuration pre-renderer for React apps.

styled-components
All the cool kids are into it, and it allows you use SCSS-like code in create-react-app (which, out of the box, supports vanilla CSS)—styling for the component age.

Okay, so, why?

One of the challenges of deploying an app built with create-react-app is that it is rendered entirely client side. Although Google can render JavaScript content when crawling a site, it doesn’t always, and there is always the risk that your JavaScript bundle will fail anyway. It’s incredibly worthwhile to send your HTML with the initial packet, which is where everything above comes into play.

When you build your site, react-snapshot fires up a server, visits each relative link, and saves a copy of the rendered page in the build folder. When you deploy it to Surge the app is “hydrated” with the JavaScript hooks, and you can spend the remainder of your afternoon sipping a crisp white wine spritzer (or apple juice and soda, depending on your personal preference).

So, let’s go.

Setting it up

First off, get create-react-app running.

npm install -g create-react-app

Then you can make a new app, which will take a while, so maybe make yourself a coffee? It’ll take the edge off that daytime wine you had.

create-react-app app-name

When the installation completes, jump into the directory and install some fancy dependencies.

cd app-name && yarn add react-router-dom react-helmet react-snapshot styled-components

Also, you 100% do not need to use yarn if you don’t want to. npm is also great, but yarn is super fast, and let’s face it we’re all still reeling from that whole create-react-app installation waiting game. Plus it has emojis!

react-snapshot requires a couple of quick changes to the default create-react-app setup.

First off, change your package.json build option.

"build": "react-scripts build && react-snapshot"

And then patch up the default src/index.js.

import React from 'react';
import { render } from 'react-snapshot';
import App from './App';
import './index.css';

render(
  <App />,
  document.getElementById('root')
);

And voila. If you run yarn build, you’ll see some sweet snapshot magic.

$ react-scripts build && react-snapshot
Creating an optimized production build...
Compiled successfully.

🕷   Starting crawling http://localhost:2999
✏️   Saving / as /index.html
🕸   Finished crawling.

✨   Done in 11.06s.

As you can see, react-snapshot is taking the app and outputting a static index.html.

It might not look like much, but it’s so great.

Still, it doesn’t do much about the key areas that a search engine is looking at—the title and metadata in the head. That’s where react-helmet comes in. It is a component that helps you manage the document head, meaning while someone navigates your app, your metadata stays in sync.

Here we’re populating the title with “You Are Doing Great”, which is true, using the Helmet component. It displays in your browser tab, and all is well with the world.

Unfortunately, when viewing the source, the <title> is still React App.

That’s where react-snapshot comes in. By using react-snapshot in conjunction with react-helmet, you can pre-populate both the head of each route, and the body, on server and client side. It is literally win-win. So let’s build it.

yarn build

🕷   Starting crawling http://localhost:2999
✏️   Saving / as /index.html
🕸   Finished crawling.

And when we look at the generated index.html?

<title>You Are Doing Great</title>

Omg, see? Even the server gets it.

For routes that aren’t snapshotted (I don’t think that’s a word, honestly), react-snapshot provides a fallback, 200.html, which behaves exactly like the non-snapshotted (still not a word) index.html. Hosts like Surge serve it automatically if no other snapshot is found, meaning react-router can grab the URL and route it appropriately. It’s automagical.

I’ve pulled together a repo that shows all this in action, called You Are Doing Great, or YADG. You can see the live version in action here.

The repo is on Github, too:
https://github.com/superhighfives/an-almost-static-stack

It’s set up with all the features I’ve mentioned, including routing, snapshotting, metadata management, almost hot-reloading, and using styled-components.

Also, if you’re looking for an example in the wild, I built my site on, essentially, the same stack.

If you have any questions leave a comment or say hi via Twitter. Alternatively, enjoy a GIF of an owl being petted.

Owls are so great.

An Almost Static Stack was originally published in superhighfives on Medium, where people are continuing the conversation by highlighting and responding to this story.

Or how to make After Effects in your browser

Update: You can view the full source code for the project, including instructions for setting it up locally, over at Github.

A couple of years ago, my band Brightly wrote a record called Beginnings & Endings. Glen Maddern and I, along with a few of our friends, built an interactive tweet-powered music video for the single Preflight Nerves, which we affectionately called Tweetflight.

It took searched out tweets that matched the lyrics of the song in real-time, and animated them against a backdrop of public domain and found footage.

It did pretty great, and we were pretty chuffed.

Since then, I’ve been a bit obsessed with the concept of interactive music videos — inspired in part by projects like Arcade Fire’s The Wilderness Downtown and Rome’s 3 Dreams Of Black — and I’ve since put out a couple of smaller scale clips, like True.

When I moved to the UK and started to work on an EP, I had a vague idea for the design, and I wanted to step away from the muted colours that have accompanied our previous releases. I knew I wanted to put out something bold and bright to accompany the first single, I Will Never Let You Go, about the lengths we go to in order to save a failing relationship, a sinking ship.

I’d collected a series of watercolours, and I liked the idea of animating them into frame using a simple ink blot mask. I pulled together a quick example in After Effects, felt pretty great about myself, and then realised I had absolutely no idea what to do with it.

I told Glen about it while were in a car, pre-dawn, driving to Golden Plains; a musical festival in Australia. I wanted to communicate the feeling of a rapidly declining relationship, that final break up over coffee, and the emotionally manipulative tug of war that accompanies it. The masks we wear and the way they deteriorate. He mentioned he’d been looking at WebGL, I mentioned the ink blot, and we started planning.

The initial concept was to build a realtime mask over any number of videos, so they could be interchanged without needing pre-rendering. We weren’t sure if it was technically possible, so we initially started playing with short square videos, overlaid on one another.

The more we talked it through, the more concerned we were about trying to synchronise multiple streams, so we decided to stitch them together into one giant one. We wrote a simple WebGL shader to display one area of the video at a time, and to do the After-Effects-style blending. It turns out, apart from a couple of sizing limits you should keep in mind (which is ultimately dependant on the graphics card), that approach works really well — and doesn’t need a particularly powerful GPU to run.

At the same time, I was experimenting with the video itself, creating short clips of myself singing the lyrics emphatically at the camera, trying to get across the core concept behind the track. It was awkward when Glen’s mate, who was staying with him at the time, walked into the apartment as I was midway through tearing at my hair, aggressively mouthing lyrics like some kind of confused wildebeest trying to eat its own reflection.

Initially I’d planned to mime the song backwards, in much the same vein as those bastions of culture and style, Coldplay, in their video for The Scientist. However, I learnt something deeply valuable while spending four hours in front of the camera. It is really, really hard to mime something backwards. Do not do it. Save yourself. Save. Yourself. Do not say I didn’t warn you.

So it was back to the drawing board. Inspired by the debauchery of Spender’s Never Again, I covered myself in make up, and over the course of the song proceeded to super-duper ruin it. I have a newfound respect for any and all who wear make up more than once in a blue moon, because mascara is hellish to take off.

At the same time I continued refining the user interface, eyes stinging, while playing with shaders via Three.js. Without exaggeration, shaders offer a phenomenal level of control over the output of WebGL. They run entirely on your GPU, which means you get a pretty ridiculous amount of grunt out of a browser. And that is not a sentence I ever thought I’d type back when I was trying to get pages to render properly in IE6.

When you fire up I Will Never Let You Go, a bunch of things happen. The browser requests the video; which includes two separate streams and the ink blog mask, and optionally, access to the webcam. These get passed into a scene, along with an image; which creates the texture and colour, and two integers, which define which video frame is being displayed, and whether or not the webcam is currently visible. It’s a relatively chunky amount of information to flick through, but WebGL seems to handle it pretty gracefully.

The webcam video gets treated slightly differently by the shader. It is turned to greyscale to try and achieve a similar visual aesthetic to the pre-recorded video, which is in turn masked in real-time using the ink blot.

I used React for the interface, which manages the views and UI while passing states to the Three.js scene, which, as a component, is agnostic. It’s a pretty comfortable arrangement, especially when using Flux to dispatch events between each separate element. I managed the browser assets with jspm, and the build with Gulp, both of which I absolutely recommend.

I focused on creating a sense of rhythm by timing the switching of the streams to the beats of the song — first in time with the pulses, then with the drum pattern. Alternating this against the webcam footage finally felt like everything coming together — like being there, in that moment, witnessing that scene.

But what’s the point? Me, in a different order? That’s not interactive. It’s a technical demo, at best. I sent it to a few friends to check out, and Will emailed me back.

“Oh wow that’s so confronting!!! :o

Is this something that could mash together all the people using the app at once into a mega-everyone thing? or just me and you (baby)?

You’re so obnoxiously talented.”

(I 100% didn’t need to leave the last line in, but Will is one of my absolute heroes, and I was so chuffed. Also, I apparently have zero shame. Go figure.)

But he had a point.

I’d considered the idea of doing something more communal, like sharing video been people watching, but with the app designed, built, deployed and CDN’d, I’d kind of had enough. I’d wrote the EP at Christmas, the first single still wasn’t out, and it was nearly September.

But the joy of refactoring is that it gives you a new enthusiasm for any project. The process of pulling together each thread to get the video live meant I suddenly had a finished thing. And a finished thing is a lot more fun to mess with.

I brought it up with Glen, and he mentioned he’d used Imgur for his typographic React-based project Typeslab (which is awesome). He linked me to some of the open-sourced code, and I started patching it together on a new branch.

I set it to surreptitiously capture an image from the webcam while the viewer watched, and added the option for them to approve it to be uploaded at the end of the video. After wrestling with the Imgur API for a little while, I had a functional prototype, and I marvelled at how awkward I can manage to look from any angle via a webcam.

And Glen made a really good point — people don’t move a lot while they watch a video. By capturing three images in tandem and stitching them together in canvas, I could recreate the idea of a moving image without the hassle of WebRTC or live streaming video or rebuilding Chatroulette from scratch.

So I did, and waited with baited breath for the result.

Upon reflection, it was not the best photo.
(And it was late. And I was in bed. And I don’t wear those glasses outside.)

Using the Imgur API I was able to store and display the images as they were captured. I rewrote the shaders in WebGL to manage the new element, marvelled at how effortless JavaScript feels in ES2015, and momentarily pondered how many dick pics I’d have to moderate if 4Chan got involved.

And in a homage to my love of Mario Kart and Patrick Swayze, I called them ghosts, because I guess they are. Little fragments of the people watching, flickering over and over again, like background noise.

It was a trial and error experience, each iteration building on the last to make something, hopefully, greater than the sum of the parts. It is a testament to the power of the web that these kind of experiences, once the bastard child of the Flash plugin, can be recreated natively with nothing more than JavaScript and a sense of adventure.

With the exception of iOS and its truly terrible WebGL video support.

I encourage you to try out Three.js, and to continue exploring the possibilities of the web. Oh, and to watch the video.

Obviously.

Watch the video

Thank you a million times over to Glen Maddern for all his help, and for being a pretty constant source of self doubt when I place myself next to his absurd genius. Thanks to Andrei Eremin for mixing, mastering and being a superhero. Thanks to Samara Clifford for taking photos that cover up how awkward I really am. And thank you for taking the time to check it out.

Brightly I Will Never Let You Go
Watch it here.
Buy it here.
Find out more about Brightly here.

If you want to get in touch, you 100% should, by email or tweet.
Thanks for listening.

Making An Interactive Music Video With WebGL was originally published in superhighfives on Medium, where people are continuing the conversation by highlighting and responding to this story.

Without pressing that big shiny red eject button

One of the caveats to using create-react-app is that you don’t get true hot reloading via Webpack. The page will reload if you make edits, not the application itself. This is usually fine for when you’re starting out, but once you want to get down to the nitty gritty it can be a pain.

Do not despair. You can get almost true hot reloading without having to yarn eject, by hooking into Webpack’s module.hot in your index.js.

By replacing the contents of your app with each edit, you no longer need to wait on a page refresh. What a time to be alive!

If you’re looking to avoid hot reloading on certain elements (for example, Three.js doesn’t love WebGLRenderer being fired up too many times) you can initialise them in your index.js, and then pass them as a prop to your application. Do I have an example? Why yes, I do. Here’s one I prepared earlier.

And there you have it. Speedy hot reloading with create-react-app. You can see it in action on React Three Playground, if you’re looking for a proper example.

PS: You’re doing a great job. Even Beyoncé says so.

Hot Reloading + create-react-app was originally published in superhighfives on Medium, where people are continuing the conversation by highlighting and responding to this story.

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.

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.

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

Harp, Gulp And BrowserSync was originally published in superhighfives on Medium, where people are continuing the conversation by highlighting and responding to this story.

The older I get, the more I realise that I do not like doing things more than once.

When I first starting making the Internets, I would spend a massive amount of cognitive energy transferring things via FTP; dragging files to Transmit, hoping I hadn’t inadvertently overwritten something super important. It was dark, people. It was a dark time.

Fortunately, this is no longer the case. You don’t have to live like this. We don’t have to live like this.

I’ve been using GitHub Pages to deploy static sites for a while now. It’s quick, easy, and pretty painless. You can easily get a static site set up and hosted in no time, and it’s free. Win win! I actually used it for the client side of Tweetflight.

If you’ve run through my Harp, Gulp and Browsersync tutorial, you can use that as the basis for deployment. If you haven’t, all you need is a repo and a directory to deploy. Easy as.

First up, you’ll want to install gulp and gulp-gh-pages, which will handle the deployment.

Getting started

So, you’ll need a package.json file, to use manage the required Node packages.

npm init

If you don’t have Node.js, you can install it here.

It will ask you some questions about your project, and it’s pretty friendly. Good for you, NPM. Good. For. You.

Right. To celebrate, let’s enjoy a photo of a cat in the snow.

So good.

Add Gulp, which powers this glorious, gorgeous beast.

npm install gulp --save-dev

Then you’ll need to add gulp-gh-pages.

npm install gulp-gh-pages --save-dev

Now, in your gulpfile.js, add the following:

var gulp        = require('gulp');
var deploy      = require('gulp-gh-pages');

/**
 * Push build to gh-pages
 */
gulp.task('deploy', function () {
  return gulp.src("./dist/**/*")
    .pipe(deploy())
});

So what’s going on here?

We’re defining a task, called deploy. You could get gulp to run a build task here, if you needed to, prior to deploying it. To do so, just update ‘deploy’, function() { to ‘deploy, [‘build’], function () { (or whatever the name of you gulp build task is) and gulp will take care of it. It’s one of the many reasons gulp is wild.

I used gulp four times in that paragraph. Calm down, Charlie.

/dist is the directory we’re deploying, and /**/* means it will deploy recursively. All files and directories inside of /dist will be included.

GitHub-ing

So, given that you’re deploying to GitHub, you’re going to need to have your site in a repository. You can see an example I set up at testing-gulp-gh-pages. If you don’t already have your site on GitHub, you should anyway. It’s awesome, and means you’ll be using proper version control for your site. Which is a huge piece of mind. Which you obviously deserve.

You’ll want to avoid pushing your whole /node_modules directory on GitHub, as it’s being managed by your package.json file. To stop this happening, make a file called .gitignore. That’s essentially a space where you can list files you don’t want to end up in source control, each on a new line.

Just make sure node_modules is listed:

node_modules

That way, when you push to GitHub, you won’t accidentally push all of your sites Node depedencies.

If you don’t want to commit your /dist, or the folder that is holding your built site, you can add that too:

node_modules
dist

It really depends on how you’re managing your folder structure. There’s no wrong way, but it’s worth noting that if your repo is public you should avoid putting any fancy paid fonts or similar in there.

In that case you’re likely better hosting them remotely with S3 or Rackspace. I use Rackspace, personally.

Custom domains

If you want to use a custom domain for your GitHub hosted site, you’ll need to do two things first.

1. Make a text-based CNAME file that will end up in the root of the directory you’re deploying. For example, /dist/CNAME. All it needs inside is the url you want to point to your new site. For me, it’s charliegleason.com.
2. Update your DNS records. GitHub has a pretty good walkthrough of how to do this.

When you’re ready to deploy, the folder you’re pushing to GitHub should have CNAME in the root. As long as that’s in there, you’re golden.

One thing I should also mention—people have flagged that because their website was hosted from my_username.github.io, their custom domain wasn’t working. Using a repository name other than my_username seemed to fix things. Just an FYI. (Thanks Nikolas!)

And then you’re all set.

Fire away!

When you’re ready to deploy, push the latest changes to your repo to GitHub.

git add . # Add any untracked files
git commit -va # Commit the changes
git push # Push it to GitHub

You’ll also need to make sure you have a gh-pages branch, if you don’t already. (Be careful when using git rm -rf ., too!)

git checkout --orphan gh-pages
git rm -rf .
touch README.md
git add README.md
git commit -m "Init gh-pages"
git push --set-upstream origin gh-pages
git checkout master

So, now you just need to run your deploy task.

gulp deploy

And voila. You can visit your fancy new site at your-username.github.io/your-reponame, or (if the DNS has propogated) at the custom domain you set up.

You can see one I prepared earlier, which is using the testing-gulp-gh-pages repo.

You’re great. Good for you. If you have any problems, I can probably help. Just email me.

Deploying To GitHub Pages With Gulp was originally published in superhighfives on Medium, where people are continuing the conversation by highlighting and responding to this story.