Guide: Add Browsersync and SASS to any WordPress Theme

12 April 2018 #Code #WordPress

This is an updated and more in-depth version of my previous blog post, written to accompany a talk I gave at WordPress Brisbane. If you’re familiar with Node, npm, Gulp, etc, you can breeze through this. I’ve deliberately included more details for first-timers. The video walks through this guide.

(Scroll forward to 4:58 to start the tutorial)

First, why?

For a long time I was developing custom WordPress websites locally using MAMP. Starting with a blank theme and writing all my CSS in one file. Then using FTP to push the files live.

While looking for a better way I came across Roots, a rather complicated framework for developing WordPress websites, which uses a lot of not-WordPress specific technologies. These tools are very complicated at first, but once you become familiar with them you won’t want to go back.

So now when I go back and update older WordPress sites, or take over other people’s projects, the two tools I miss most are Browsersync and SASS. They have nothing to do with WordPress but will make your life so much easier. By:

  • Splitting your styles into multiple SASS files
  • Concatenating those files into one minified CSS file
  • Watching all your files for changes and reloading the browser automatically
  • Spinning up a local proxy which you can then use on any mobile device on the same network

Basically, code smarter and faster, even in a not-so-smart development environment!

Get Ready

This guide is aimed at WordPress developers who’ve never used the command line before. But are comfortable developing WordPress themes locally (on their own computer).

  1. Not familiar with the command line? Wes Bos’ free Command Line Power User course will get you up to speed.
  2. Don’t know what NodeJS is? You don’t need to. Just follow the instructions to install.
  3. Don’t know what npm is? Same again. Just follow the instructions to install.
  4. Don’t know what Gulp, Browsersync or SASS are? You’re about to.

Get your local WordPress install started. Let’s go!

Use npm to get what you need

I’ve used BlankSlate as a starter theme many times before. It’s completely blank. It’s what I’ll be using in this guide. But you can do all of this guide in existing themes as well.

From the command line, go to the directory that your theme is in.  And run the following two commands:

npm init

You’ll be asked a series of questions, but you can just hit return after each one. There’s no real need to fill these out for our purposes here.

npm install gulp gulp-sass gulp-concat browser-sync --save-dev

What is this doing? Well:

  • npm install is going to install a bunch of utilities for this specific project
  • gulp is what we’ll use to run all of these utilities
  • gulp-sass will allow us to write SASS files
  • gulp-concat will pull those SASS files together into one minified CSS file
  • browser-sync will watch all our theme files for changes, serve the site into a browser, and automatically reload as we work
  • --save-dev is going to save all these utilities to the project, just for development

Add gulpfile.js

To power everything we just installed we’ll need a file in the root directory of the theme, called gulpfile.js. When we run the Gulp command later it’ll look for this file and then do everything in it.

You can re-use this file between projects, so long as you modify anything specific to the project.

Take a look through the file and do the following:

  1. Browsersync is going to watch any files with the extension .scss inside the folder /sass/ – so create this folder and a blank main.scss file inside it. It will also watch any .php files in the theme.
  2. Modify the proxy: setting to match your local development URL
  3. In the next section, we see the .scss files will be concatenated and minified together into one .css file: /css/styles.css
  4. Lastly, when the gulp command is run, it’s going to do all of the above.


Back in the command line, run the command:

  • gulp

The task will complete and a new browser window will open up with your site. It should also have taken any styles in your /sass/main.scss and minified them into /css/styles.css.

Only problem is your theme doesn’t point at that file yet. Open functions.php and add the following code:

This will inject our /css/styles.css file into the theme, and use the theme version number as a nice little cache-busting tool should you ever need it.

if (!is_admin()) {

$theme = wp_get_theme(); // Used for cache busting

wp_enqueue_style('Style', get_template_directory_uri() . '/css/styles.css', array(), $theme->get( 'Version' ), 'all');


Going live

However you push your new theme live to your hosting, keep in mind the following:

  • You theme now has a large folder node_modules inside it. You don’t need this on the live site, so just keep it in your local version.
  • Your .sass files don’t need to be up on the live site either, but it won’t do any harm to have them there

Go beyond

You’re just getting started. Using Gulp and npm you can add all sorts of extra tools to your workflow. Including image optimisation, code linting and more. At that point you might want to look into a more high featured theme like Sage as a starting point.

“But what about…”

The other thing about leaving your PHP/CSS WordPress moat and venturing into tools like npm and Gulp is the never ending list of ways ‘you’re doing it wrong’.

For example Gulp is out of favour now for Webpack, and Webpack will be unseated by something else in future. But all of the above works, is simple, and should get you started in this arena.