Sometimes I’ll use one of the pre-built Genesis themes from StudioPress to give me a head start on a project. While I’ll almost always rebuild the code, their designs are minimal, attractive, and place focus on the website content ahead of flashy features and code bloat. They give a solid base to work from.
Because they don’t include development files I usually spend some time adding Gulp support to the theme, converting the theme to SCSS, and updating all of the JS files so they’re concatenated and minified.
What are the benefits of converting an existing theme to use Gulp WP Toolkit?
Being comfortable on the command line
The requirements to get started with Gulp WP Toolkit are a command line tool (Terminal on Mac, or I like to use Cmder on Windows) and having Node and Gulp installed and accessible. Check your version by running
node -v and
gulp -v from the command line.
- If you need to install Node, you can do so by downloading the installer from https://nodejs.org/en/download/.
- Once Node is installed, you can install Gulp globally by typing
npm install -g gulpin your command line.
Adding Gulp WP Toolkit to the Infinity Pro theme.
While this guide is specific to the Infinity Pro theme, the same principles will apply to most other StudioPress themes.
1. Add a package.json file and run npm install.
package.json file can be quite basic, it only needs the minimum amount of detail to get started. You’ll see that I’ve also added the
gulp-stats package, which records the length of time each task takes to run, and the order in which they complete and reports back when your build process finishes.
npm install once your
package.json file is in place, and our depedencies will be downloaded to a new
node_modules folder. If you’re using version control to track changes to the theme you’ll want to ignore this folder.
2. Create your Gulpfile.js.
If you’ve used Gulp before, you’ve probably had experience of Gulpfiles that span hundreds of lines of code. With Gulp WP Toolkit, things are much simpler. All of the tasks you’d expect are present, but they’re contained within the toolkit itself and you don’t need a monstrous Gulpfile to make use of them. At the moment, just having installed Gulp WP Toolkit, our Gulpfile is basic.
As we configure Gulp WP Toolkit to work with the Infinity Pro theme we’ll update the configuration by adding to
3. Copy theme assets to a /develop directory.
I want to keep my original files separate from my compiled production files, so I create a directory called
/develop and place SCSS files, original images and source JS files there. These are the source files for my project. In the case of the Infinity Pro theme, I’ve moved the images, css and js folders inside
/develop. I’ve also moved the theme
screenshot.png file into the
When I run
gulp build, Gulp WP Toolkit is going to find our images folder automatically and will optimize and output the images into an images folder in the theme root. The theme screenshot will also be optimized and moved to the right place. In order to correctly compile our CSS and JS files, we’ll need to set the correct input paths in our Gulpfile.js. I’ve also taken this opportunity to rename the CSS files and folder to SCSS, so we have
develop/scss/style-front.scss. Their contents will remain the same for now, though.
4. Set up SCSS output.
The first setup task we need to complete is to remove the theme header from our
style.scss file and add it to the theme configuration in our Gulpfile. When complete, the Gulpfile.js should look like this:
* Sidenote: While compiling this post I realised that Gulp WP Toolkit doesn’t account for a Template Version in the stylesheet header. I’ll add that to the toolkit, and update this tutorial when it’s done.
Gulp WP Toolkit will automatically identify our
style.scss file, and compile and output it to the theme root, but we will need to add our own configuration for the
style-front.scss file. We need to set our output filename, and the source and destination paths. The updated config should look like:
5. Set up JS output.
/develop/js but they’re not being compiled because Gulp WP Toolkit doesn’t know about them.
From reading the Infinity Pro
functions.php file, I can see that the files
responsive-menus.js are loaded on every page, so it makes sense to concatenate these files into a single
infinity-pro.js file. We will need to update the
functions.php files to reflect this change, though.
Specifically, we will need to remove calls to the individual files and replace them with the single file. We’ll also need to update the
wp_localize_script block which passes data to the responsive menu script, as the handle will likely now be incorrect.
Gulpfile.js should read as:
And in our
functions.php file we can remove the now unnecessary script calls for the individual files, and instead change the
infinity_enqueue_scripts_styles function to read:
6. Build the theme, and continue to develop.
With all of the above setup and configuration in place, we can run
gulp build at our command line. This tells Gulp that we’re ready to compile all of our assets. Gulp WP Toolkit will log key events in your terminal app and will notify you when the build process is complete. All being well, we should still have a fully functional Infinity Pro theme, with assets now optimized, compiled, concatenated and more by Gulp WP Toolkit.
At this point, you probably want to continue on with customizations. If you’re working locally then you can use the power of Browser Sync to live-reload your web browser when you make changes to PHP, CSS or JS files in your editor. Setting this up requires a little more configuration, only three lines. Added to your Gulpfile, the finished article should look like:
Lines 40-42 are key, where we tell Gulp WP Toolkit that we’re using a local site with a URL of
With these lines in place, you can run
gulp serve to launch a new BrowserSync session and see your code changes update in the browser in real time.