Ahmad Awais


Introducing WPGulp: An Easy to Use WordPress Gulp Boilerplate

Ahmad AwaisAhmad Awais
While this article is still helpful for beginners. It is a bit outdated. WPGulp has evolved a lot. Make sure you read the official documentation at WPGulp’s GitHub Repo — I’d ask you to star the repository to keep up with the updates.

So, you have never used Gulp before? I am here to help you get started. Yes! You can use WPGulp and ask as many questions — in the comments below — as you want. And I will make sure you get a kick-start in professional WordPress Development.

I have had been using Gulp for over two years now. Gulp makes things easier; it is simple to use JavaScript-based task runner. You can use Gulp to automate bits of your workflow.

If you are a subscriber to this blog, then you might have come across my Advanced Gulp Workflow for WordPress Themes. My workflow has changed a lot since then, but you can still get a pretty good idea of just how powerful Gulp is.

I wrote about Gulp in August, this last year. To my surprise, what I thought was a mere brain_dump() turned out to be a popular post in the WordPress community. Most of the feedback was pretty great, but quite a few people asked for a beginner-friendly version of that post.

While I was thinking of building a boilerplate for Gulp, one of my friends Roy Sivan invited me over to talk about Grunt vs. Gulp which is best for your WordPress build? at a podcast called TheWPCrowd. For that podcast, I created this boilerplate and named it WPGulp.

Introducing WPGulp

Make sure you star the WPGulp GitHub Repo for updates!

WPGulp is a Gulp boilerplate for your WordPress project (type agnostic i.e. works for both WP plugins and themes). Right now, it is built with beginners in mind, but in the long run, I have plans to put more branches at this repository with portable Gulp tasks. So, go ahead and Star the repository. (Or follow me at GitHub).

WPGulp Boilerplate is a simple implementation of Gulp for WordPress. It implements following tasks:

Step #0: Beginners Get Started Here!

Let’s begin with the configuration. Since we are discussing Gulp here, I’d like to avoid any explanations related to Node, Terminal, Git, etc. When I started using build tools, I didn’t know anything about these terms except their names, of course. So, you need not to worry about it. Once you set it up, you’ll look back at your old projects and will laugh out loud at yourself (Too soon?).

P.S. I’m a Mac user, and all these configurations are meant for a Mac user. But I’m sure you can find more info about Windows or Linux based setup online.

Step #1: Installing Node & NPM Node Package Manager

Node & NPM

Before you start using Gulp, you need to install Node, which will also install NPM i.e. Node Package Manager. You only need to install this once. Node.js can be downloaded for Mac, Windows, and Linux at nodejs.org/download/. You can also install it from the command line using a package manager.

Once you have installed Node, open the terminal and enter:

node -v

The installed Node.js version number will be displayed. You can do the same for npm — the Node.js package manager — which is used to install modules.

npm -v

If either command fails, check you’ve typed that command in lowercase. Still no good? Verify you installed Node.js correctly.

Step #2: Let’s Install Gulp


Gulp needs to be installed globally in your OS before you start using it in a project. You can install it with the following command.

sudo npm install gulp -g

The -g specifies that the install is global. Now, verify that Gulp has been installed by the following command:

gulp -v

Step #3: Setup Your WordPress Project

Clone the repo

Go to your WordPress project (plugin or theme) folder and download both gulpfile.js and package.json files in the root. Or else if you are starting a new project, then you can just clone the WPGulp repository and start from there. Just like I did in the screenshot above. I created a folder  WP-Project and cloned WPGulp repo inside it.

Step #4: Understanding the package.json File

The Package.json is the file which is used by NPM to manage the packages for your project. You create it in your project by npm init command. After installing Gulp globally and creating a package.json file via npm init command, you can install gulp via this command npm install gulp --save-dev. This will install Gulp and will automatically save it in the package.json file.

But with WPGulp you can ignore all that since that’s what a boilerplate does, you get a pre-built package.json file.

The package.json file in WPGulp is pretty much self-explanatory. There are project related details from line #1 to line #9 which you need to change, and after that, there are devDependencies from line #10 to line #22 which you don’t need to change. You don’t need to edit anything after line #9. These are the gulp plugins we will install in our project.

npm install

So, after adding both gulpfile.js and package.json files in the root folder of your WP Project, run the following command.

sudo npm install

This will create a node_modules folder (where Gulp and plug-in code resides) within your WordPress project folder, which in my case is  WP-Project . The above screenshot shows everything got installed without any error. You can ignore the warnings (if any show up in the terminal while installation is being run).

Step #5: Understanding Gulp

Gulp needs a gulpfile.js file in the root folder of your project to work. I started using Gulp only because it made more sense to write code over configuration (since Grunt has a JSON-like syntax while Gunt is JavaScript).

The Gulp API contains only 4 top level functions. Which are:

That’s it. No you know almost everything there is to Gulp. Think of Gulp as a stream of data; you can input anything anywhere in the stream and take an output of anything anywhere along the way (Confused? Let it go). gulp.src uses .pipe for chaining its output.

Step #6: Understanding the gulpfile.js File

Let’s take a look at the gulpfile.js file present in WPGulp. I have built a portable file which can be used with any WordPress project. It consists of following portions

  1. Configuration: Project Configuration for gulp tasks.
  2. Load Plugins: Load gulp plugins and assign them semantic names.
  3. Task styles: Compiles Sass, Autoprefixes it and Minifies CSS.
  4. Task vendorJS: Concatenate and uglify vendor JS scripts.
  5. Task customJS: Concatenate and uglify custom JS scripts.
  6. Watch default Task: Watch for file changes and run specific tasks.

#1: Configuration

In this portion, you can define where your files are present and where you want to store the output. And which files you want Gulp to watch for changes. Read the comments to understand the code below.

#2: Load Plugins

All the plugins that are being loaded are present in this portion. One could use the gulp-load-plugins package to load plugins, but I like to keep control of what is getting included and what isn’t, which is why I choose to include plugins this way. It also helps in debugging while updating Node or any other package. Read the comments to understand the code below.

#3: Task styles

Make sure that your WordPress theme base stylesheet begins with /**! otherwise, the minifycss might remove the WordPress comment at the top. Which could render the theme useless since WP won’t recognize it as a theme. You can check a demo WordPress theme implementation of WPGulp at WPGulpTheme. Moreover, read the comments to understand the code below.

#4: Task vendorJS

Concatenating JavaScripts and uglifying them can help speed up the page load time. Read the comments to understand the code below.

#5: Task customJS

Same here, concatenating JavaScripts and uglifying them can help speed up the page load time.Read the comments to understand the code below.

#6: Watch default Task

Finally the default task, which will trigger all the other tasks in our file. Read the comments to understand the code below.

That’s all there is.

The Complete Code of gulpfile.js

Here’s the complete code of the gulpfile.js file.

Step #7: Running Gulp

run gulp

Finally, after configuring the gulpfile.js, you need to run the gulp command, which will run the default task, which in turns triggers the styles, vendorsJs, customJS tasks and finally starts watching your .scss and .js files. So, here is the command:


Looking Forward!

Whew! That was a lot. Looking forward to your comments. Let me know if I missed something or if you didn’t understand a step or two.

Here are the resource links, just in case


Since I wrote this article, WPGulp has grown a lot and it now supports the following tasks.

What Can WPGulp Do?

  1. Live reloads browser with BrowserSync
  2. CSS: Sass to CSS conversion, error catching, Autoprefixing, Source maps, CSS minification, and Merge Media Queries.
  3. JS: Concatenates & uglifies Vendor and Custom JS files.
  4. Images: Minifies PNG, JPEG, GIF and SVG images.
  5. Watches files for changes in CSS or JS
  6. Watches files for changes in PHP.
  7. Corrects the line endings.
  8. InjectCSS instead of browser page reload.
  9. Generates a .pot file for i18n and l10n.
While this article is still helpful for beginners. It is a bit outdated. WPGulp has evolved a lot. Make sure you read the official documentation at WPGulp’s GitHub Repo — I’d ask you to star the repository to keep up with the updates.

If you liked what you read, Tweet about WPGulp and subscribe to my WordPress newsletter below.


WPTakeaway: Premium WordPress Newsletter!

Takeaway my professional opinion about Full Stack WordPress Development, building a business, growing a family, and everything web! Delivered to your inbox twice a month. 👻 I hate spam! Pinky Promise!

🔥 Ridiculously hard-working Full Stack Web DeveloperRegular WordPress Core Contributor 📣 TEDx Speaker ✌️ Spends 50% of his time building FOSS (Free & Open Source Software) used by over 10,000 Developers 🎖 WordPress Advocate & 🙌 Community Evangelist 👻 DevOps fanboy 😂 Cracks silly jokes 💜 Loves his wife (Maedah) 🍕 Learn more about Ahmad ↣

Say 👋 on Twitter @MrAhmadAwais | Subscribe to the WordPress Takeaway!