Ever since I first tried Grunt, I’ve been a huge advocate of task runners. Not only do they significantly speed up your development, they completely automate some of the most repetitive tasks you do on a day to day basis. But more importantly, when you start using them, a plethora of other tools and best practices often emerge to assist you with your workflow. And what developer isn’t keen on constantly learning new and amazing tools?

While Grunt isn’t exactly my cup of tea, Gulp is, which is why I already wrote a tutorial on speeding up your theme development with it. But now, after speaking with a couple of my developer buddies at WordCamp EU 2015, decided to release a starter theme (based on Underscores) that will have a basic Gulp script in order to educate yourself and get up to speed with a few simple commands.

Requirements

For this theme to fully function, you’ll need two things installed on your computer: Node.js and Bower. The latter is a frontend dependency manager (powered by Node). Essentially it replaces downloading a script manually and putting it into your js directory with a simple command like this:

$ bower install jQuery

Why is that important? If you look at any of the best selling themes on ThemeForest, you’ll quickly notice how much external javascripts/stylesheets they come with. Those are all dependencies, because the theme depends those to be included for it to function properly.

Install it, use it, love it.

The last thing you’ll also need, of course, is Gulp, which should be pretty trivial to install once you have Node.js up and running.

Since we want to enhance our workflow, there should be an existing Apache/Nginx running on your development machine, with everything needed in order to run WordPress properly (which is outside the scope of this article - we covered that already).

Download and activate Sip

Visit our GitHub repository and clone it into your themes directory:

$ cd /your/WordPress/wp-content/themes/
$ git clone git@github.com:codeablehq/Sip.git

Now login into WordPress and activate the theme, then return to the terminal, which is where you’ start Gulp. But before that, we need to make sure all dependencies are installed (forgetting this is a very common mistake we all do):

$ npm install
$ bower install

These two commands will look into package.json (Gulp’s requirements) and bower.json (Bower’s requirements) and install the necessary dependencies.

Gulp tasks overview

The most important file in this theme is gulpfile.js. Open it and let’s go through it together:

  • The first 10 lines just require in al the necessary scripts and assign them to variables, so we can call them from our tasks
  • Line 15 defines a default error handler which prevents Gulp to exit if an exception (an error) occurs. If you write Sass, chances of that happening are relatively high, so better to have a guard in place that will stop Gulp processing rather than exit it.
  • Line 23 is the most important task. It sets up a tiny BrowserSync server that proxies all requests to our WordPress and injects a tiny JavaScript on each one; This JavaScript is responsible for listening to possible changes and reloading your browser when they occur. Change the proxy value according to what URL your local WordPress is listening on (usually localhost or localhost.dev). Once BrowserSync server is running, we also set up file watchers that trigger other tasks when files change.
  • Line 47 is our Sass-to-CSS task. When ran, it looks at the main sass style (style.scss), preprocesses it, then saves it into style.css (more on that shortly)
  • Line 58 checks all our JavaScript files, lints them and reports potential problems. In order for it to work properly, you also need a .jshintrc file, which you can configure to fine-tune your error reporting. Warning: this task may ruin your day :)
  • Line 69 is our default task (every gulpfile should have at least one, default task). Note the second parameter; An array of tasks that need to be executed before the default one is. This task is most often empty because the dependant tasks take care of pieces that make up our workflow.

Note: This theme also comes with a surprise: a fully configured Sass framework that should help you get started in no time. It’s author Zell Liew wrote an excellent ebook on Susy (Sass-based Grid framework) and agreed to relase it to our awesome WordPress community. Thanks Zell!

Run Gulp

Now that we have everything in place (and hopefully understand how it works as well), it’s time to run Gulp:

$ gulp

Once you do that, a new browser window should pop up, with http://localhost:3000 and your WordPress site loaded. Even if you click around, everything should function properly, regardless of what your original WordPress URL is.

In order to test it, I recommend opening scss/_shame.scss and changing the default anchor color to something other than blue.

You should see all the links on your WordPress site change color without the browser being refreshed. I know this is not a huge thing but I was mindblown for the first time I’ve seen that happen as I didn’t even know that was possible!

Even if you click around your WP site, BrowserSync will keep connecting itself so no matter what page you’re on, the updated CSS will always be injected on the page in real time.

Furthermore, if you update any of the .php files in your theme, the browser will refresh automatically, no need to put focus out of your code editor.

It's time WordPress developers embrace the modern tools for theme development. Starting with Gulp Click To Tweet

This theme, like Underscores, is in no way complete but only the starting point and I encourage you to explore the Gulp ecosystem on your own to develop best practices, adapted to your workflow.

I hope you enjoy building off the theme as much I did enhancing it! :)