How I use Gulp when developing WordPress themes

I’ve built a lot of WordPress themes over the years, and the quality of my work has been improving gradually as I’ve learnt new techniques and embraced new technologies.

One major leap over the past year has been my use of the Gulp task runner. I’ve been able to use it for a number of important tasks:

• Compiling SCSS.
• Optimizing images.
• Installing bower components.
• Creating language .pot files.
• Concatenating JavaScript.
• SCSS & JS Linting.
• Adding BrowserSync support allowing instant reload in web browser.

While not as advanced as some, my Gulp setup allows me to quickly and easily get up and running when creating a new WordPress theme.

One thing which I didn’t want to do when using Gulp, was tie it in to my starter theme directly. A lot of starter themes will come with a bundled Gulpfile.js and other associated files. I’ve intentionally separated my Gulp build tasks into a separate GitHub repository, which can be pulled in to whatever theme I’m working on.

For example, I might want to convert an existing Studiopress theme to use Sass, and benefit from the other features of my Gulp build.

To get up and running with my Gulp setup, enter your theme directory and from the command line, run:

git clone https://github.com/craigsimps/gulp-build-tasks gulp

This command will clone my Gulp configuration to your theme folder, inside it’s own /gulp/ directory. From there, enter the directory in the command line and run npm install to begin installing the various dependencies required.

At this point, you can also open the config file, which is located at /gulp/tasks/config.js, and configure your project paths. Script concatenation is controlled from within /gulp/tasks/scripts.js where you can enter the source files in the gulp.src array. As I’m typing this, I realise it would be more efficient if the array of source JS files was created within the project config file so I’ll probably make this change soon.

When all of the node modules have been installed, you will have a number of key Gulp tasks at your disposal:

• gulp runs the default gulp watch task, looking for changes in code and compiling as required.
• gulp serve calls the default gulp watch task and launches BrowserSync session using the local url defined in config.js.
• gulp build calls gulp bower to load dependencies, then runs gulp scripts, gulp styles, gulp images and gulp i18n. Should be used when setting up a new installation to compile all of the theme files from /develop/ into /assets/.
• gulp check performs a SCSS lint and JS lint, referencing a .scss-lint.yml and .jshintrc in the theme root.

The following tasks can also be run independently.

• gulp bower will check for a bower.json in the theme root (one level up) and run bower install (this task now runs as a dependency of the styles task).
• gulp jshint will lint your JavaScript (within /assets/js/ only) using standards defined in .jshintrc in theme root.
• gulp i18n generates a translations file at /languages/textdomain.pot, where textdomain is defined within config.js.
• gulp scripts concatenates all scripts from /develop/js/ to a single file (theme.js) in a /assets/js/ folder in the theme root.
• gulp images optimizes and outputs all images from /develop/images/ to /images/ within the theme.
• gulp scsslint runs through the SCSS files in /deveop/scss/ and reports any issues.
• gulp styles compiles SCSS in /develop/scss/style.scss to style.css and style.css.map in theme root.

The basic configuration of my Gulp tasks assume that you’ll be working from (and have all your source files) within a /develop/ directory inside your theme, and that the compiled and optimized files will be output to an /assets/ folder within your theme. This means that when committing the theme to version control, you would only usually track the /develop/ folder.

I intend making a number of improvements to my build process over the coming weeks and months, I’d like to introduce full support for right-to-left stylesheets and associated Sass map. I’m also planning to put together a short video which shows installation and use of the various tasks. Dealing with Bower components is also something high on my agenda, specifically making sure that key files are transferred to the /assets/ folder, rather than having to reference the /bower_components/ folder (or in this case /vendor/ because I have modified the installation path).

In the meantime, you can of course check out the current repository at http://github.com/craigsimps/gulp-build-tasks, and put forward your ideas and suggestions for further development.