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.
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 open sourced my advanced gulp workflow which I use while building premium WordPress themes http://t.co/evardVlS5O pic.twitter.com/wawo4z1qES
— Ahmad Awais (@MrAhmadAwais) August 24, 2015
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.
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:
- Sass to CSS conversion
- JS concatenation
- Watch files for changes
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
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:
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.
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
-g specifies that the install is global. Now, verify that Gulp has been installed by the following command:
Step #3: Setup Your WordPress Project
Go to your WordPress project (plugin or theme) folder and download both
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
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.
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.
So, after adding both
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
The Gulp API contains only 4 top level functions. Which are:
gulp.taskDefines your tasks.
gulp.srcPoints to the files you want to use i.e. the source.
gulp.destPoints to the output folder i.e. the destination.
gulp.watchHelps watch files for changes i.e. File change can trigger a particular task E.g. Change in a CSS file can trigger the
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).
.pipe for chaining its output.
Step #6: Understanding the
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
- Configuration: Project Configuration for gulp tasks.
- Load Plugins: Load gulp plugins and assign them semantic names.
styles: Compiles Sass, Autoprefixes it and Minifies CSS.
vendorJS: Concatenate and uglify vendor JS scripts.
customJS: Concatenate and uglify custom JS scripts.
defaultTask: Watch for file changes and run specific tasks.
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.
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.
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
Here’s the complete code of the
Step #7: Running 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:
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