For the first part in my ‘Automating WordPress Development‘ series I felt I should start with setting up Gulp. I resisted using Gulp (or Grunt etc) for a long time. I found it complex to setup, and it seemed like it would just be more code to maintain. Plus it used the command line; something I, as a designer, try to avoid. But eventually I got it running and found that it wasn’t as hard as I had imagined. Plus the benefits of running it outweighed the negatives of maintaining more code.
What does Gulp do?
Gulp is a task runner. It performs simple tasks on files you are working with. It can also watch files and run processes on them when they change. A common example is it can watch SASS files for changes, and then compile the SASS into CSS automatically (despite it being a very common use case I use Codekit for this and not Gulp :)).
So what do I use it for? I use it to compile theme zips, generate rtl.css files, check theme text domains, compress images, and much more. But first we need to get it running.
Setting up Gulp
I actually followed the tutorial written by Chris Coyier for setting up Grunt, called Grunt is not weird or hard. Chrises article outlines things nicely – however there are a few differences between Gulp and Grunt.
The process for setting up Gulp is:
1. Install NodeJS
Gulp uses NodeJS to run, but don’t worry – this is the easiest step. Just download the install file from NodeJS, and run it. This installs Node, and something called NPM (Node Package Manager). This is what we will use to install Gulp, and its plugins… on the command line.
2. Install Gulp
Open the command line (I like iTerm2 version 3 for the Mac). It’s a single command to install Gulp using npm.
npm install --global gulp-cli
3. Setup your project
Navigate to your project directory. For WordPress development I use the themes directory. Then run the following command:
npm init
This will create a package.json file in your project root and set the basic properties. Just follow read the text and answer the questions. You will need to do this any time you create a new project. You should then add gulp as a project dependency with:
npm install --save-dev gulp
And you’re done!
First Task
The thing is, you have gulp setup, but it doesn’t currently do anything. At all. We now need to create some tasks to run. One of the simplest tasks I have in my automation setup is checking theme textdomains are correct.
TextDomains are identifiers used in translations. They tell the WordPress localization code which language file to use for the current translation string. I setup the checker because I (currently) have 20 themes to manage, and when updating them I often copy and paste code between files – textdomains and all. So it’s good to have a reminder if I forget to change a textdomain.
You can read more about textdomains and localization in WordPress on the WordPress theme developer site.
To run tasks I need to create a gulpfile.js – since I run the same tasks on multiple themes I put this in the themes directory. Note also that it’s a js (javascript) file. All the code we’re going to write is javascript. So if you want to do something custom, it’s likely you can use some simple javascript to do it. Note that JQuery won’t work – although there are some jquery style Gulp plugins, but that’s getting ahead of ourselves 🙂
So we have the gulpfile.js ready, and now we need to install some Gulp plugins since they do most of the work for us. For this task we need two plugins. Gulp util, and Gulp Checktextdomain (all npm packages can be found on the npmjs.com website). We can install them with the following two commands (also found on npmjs package pages).
npm install gulp-util --save-dev
npm install gulp-checktextdomain --save-dev
Once installed we can code. Open up gulp.js and add the following at the top of the file:
This requires the different plugins we’ve installed, and assigns them to variables so that we can reference them in the tasks. The check text domain task looks like this:
What this code is doing is:
- Creating a new task called ‘checktextdomain’
- Grabbing the theme slug from a command line parameter (the theme folder name and textdomain should match)
- Select all the theme files –
'./' + theme_slug + '/**/*.php' - Send the files down the Gulp pipe through the checktextdomain command. This is a generic command that will work with any programming language so we have to tell it all of the WordPress translation functions.
To execute the task against the twentyfifteen theme you would run the following on the command line:
gulp checktextdomain --theme twentyfifteen
However this would create an error – because I’m doing something a bit different. I am using a command line argument, which isn’t that common in the world of Gulp. I assume the reason other people don’t use this method is because they develop each theme as a separate project, so they would have different gulpfiles for each theme. I develop all of my themes on a single local WordPress install and then switch between themes as I go – so for me it makes sense to have a command line parameter so that I can specify which theme I want to test.
To add this we’re going to make use of the util plugin we installed earlier. The function is simple but I use it in a lot of the commands so I keep it as a separate function.
A couple of things to note here.
- If there’s no command line value set then I default to ‘granule’ – this is my starter theme, and I know it will always exist so it’s a good default for both testing and fallback.
- I am using console.log – if you use this in Gulp then it outputs content to the command line. So in this case I tell the command line which theme I am working with to confirm the selection and because I like to see the command line scroll down a long way. It makes me feel clever.
Now when we run the command it should work fine. If there are any issues with the text domain in your test theme these will be output to the command line. You can then go through and fix them, and run the test again to make sure you did it correctly.
Conclusion
If you followed this correctly (and I explained it correctly) then you should now have NodeJS set up, along with a working Gulp install, and a first Gulp task.
I’ve probably overcomplicated things – both in the way I have set Gulp up, and the way I have explained the process – so if you have any feedback or suggestions then please feel free to let me know in the comments or on Twitter.
Was it good/ useful/ a load of old rubbish? Let me know on Mastodon, or BlueSky (or Twitter X if you must).
Link to this page
Thanks for reading. I'd really appreciate it if you'd link to this page if you mention it in your newsletter or on your blog.