Ahmad Awais

NAVIGATE


SHARE


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.

JUST A NOTE!
πŸ‘¨β€πŸ’» I’m teaching thousands of devs how to become VSCode Power Users β†’
βœ… This site is super fast?! It’s hosted with Kinsta on Google servers β†’

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

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:

gulp

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

WPGulp UPDATES:#

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.

JUST A NOTE!
πŸ‘¨β€πŸ’» I’m teaching thousands of devs how to become VSCode Power Users β†’
βœ… This site is super fast?! It’s hosted with Kinsta on Google servers β†’

I help businesses understand developers πŸ“Ÿ Just launched Node.js CLI Automation Course πŸ‘¨β€πŸ« Edutainer at VSCode.pro 🎩 An award-winning GitHub Star open-source engineer & advocate 🦊 Google Developers Expert Web DevRel 🌳 Node.js foundation Community Committee Outreach Lead ✌️ Author of various open-source dev-tools and software libraries used by millions of developers worldwide ⓦ WordPress Core Developer πŸ“£ TEDx Speaker πŸ™Œ Leading developers and publishing technical content for over a decade πŸ’œ Loves his wife (Maedah) ❯ Learn more β†’

Say πŸ‘‹ on Twitter @MrAhmadAwais | Subscribe to the Developers Takeaway!

πŸ“¨

Developers Takeaway

Takeaway my professional opinion on open-source, developer relations, growing your business with family, and everything in between! Delivered to your inbox a couple of times every year. I'm even funny at times. I hate spam β€” pinky-promise!

πŸ‘¨β€πŸ’»πŸ‘©β€πŸ’» 118,947 Developers Already Subscribed
Comments 41
  • Andrew Blackwell
    Posted on

    Andrew Blackwell Andrew Blackwell

    Reply Author

    Perfect beginner boilerplate. Certainly compliments your previous Advanced Workflow post. Thank you for sharing and look forward to streamlining my process with gulp, bower, etc.


  • xeero 07
    Posted on

    xeero 07 xeero 07

    Reply Author

    perfect.
    btw which zsh theme you are using? it looks nice :)


  • Takeshi Kriang
    Posted on

    Takeshi Kriang Takeshi Kriang

    Reply Author

    Awesome, thanks for sharing this.
    Could you please add Browsersync to the workflow?


    • Ahmad Awais
      Posted on

      Ahmad Awais Ahmad Awais

      Reply Author

      That’s the plan. I’ll be adding a branch with BrowserSync.


  • Josh
    Posted on

    Josh Josh

    Reply Author

    I just read your AWESOME tutorial. Mind if I ask you a few questions?

    -Do you use some kind of live reload when developing locally?
    -Why concatenate vendor and just JS separately?
    -And if you use modernizr, do you put it in with the vendor scripts or run it along in the ?


    • Ahmad Awais
      Posted on

      Ahmad Awais Ahmad Awais

      Reply Author

      Hey, Josh!

      Glad I could help.

      -Do you use some kind of live reload when developing locally?

      Yes, I use BrowserSync. I plan to add it to the WPGulp repo. Make sure you have starred it.

      -Why concatenate vendor and just JS separately?

      CustomJS scripts are dependent on VendorJS scripts. Which means they must be included after their vendor dependencies have already bee enqueued. That’s why I keep these two separate. And I enqueue the CustomJS file with VendorJS as one of it’s dependencies.

      -And if you use modernizr, do you put it in with the vendor scripts or run it along in the ?

      No I don’t. If you want to exclude a particular script, you can easily do that. Just add a glob path with ! in front of it. E.g.

      gulp.src(['./assets/js/vendor/*.js', '!./assets/js/vendor/modernizr.js'])

      I hope it helps.


  • Amir Hameed
    Posted on

    Amir Hameed Amir Hameed

    Reply Author

    Aslam o Alaikom Awais bro,
    Not to discourage you, I just want to say that , there were other such frameworks already doing all these things , then why building WPgulp. Because if one start using gulp he can make this small setup himself. I think you should add something helpful regarding WordPress that other frameworks and repos are not offering.


    • Ahmad Awais
      Posted on

      Ahmad Awais Ahmad Awais

      Reply Author

      Hey, Amir!
      Thanks for dropping by. I get what you are talking about. The thing is I am not competing with anyone. In August last year, I share my advanced Gulp workflow, if that’s what you are looking for. WPGulp is an effort to build a boilerplate, that anyone could use in any WP project. (Which was not the case with the advanced workflow I shared). I have plans to add more and more tasks in the form of branches to WPGulp β€” in near future. Since that’s how I plan to open source my current Gulp workflow. I hope you get the point.

      BTW you are more than welcomed to send pull requests.


  • Henning
    Posted on

    Henning Henning

    Reply Author

    Very helpful, thanks. Code is very nice – only thing that I can not get to work is browsersync refresh when changing SCSS file … .


  • Henning
    Posted on

    Henning Henning

    Reply Author

    Ah okay, it has to be “gulp.watch( styleWatchFiles, [ ‘styles’, reload ]” (with “reload”) to reload automatically when changing SCSS file, haven’t noticed that … .


    • Ahmad Awais
      Posted on

      Ahmad Awais Ahmad Awais

      Reply Author

      It will trigger a reload every time there is a change. Not everyone wants that. I don’t! I let my styles get included in the form of an injected CSS. You can uncomment this line to allow BrowserSync to inject CSS.


  • Spencer
    Posted on

    Spencer Spencer

    Reply Author

    If you are using node v4 or greater, gulp-combine-media-queries will not work, so I switched to using gulp-merge-media-queries.


    • Ahmad Awais
      Posted on

      Ahmad Awais Ahmad Awais

      Reply Author

      Those merge media queries sometimes do create a problem. I have changed that several times in WPGulp. WPGulp now uses gulp-merge-media-queries.


  • Mike Schinkel
    Posted on

    Mike Schinkel Mike Schinkel

    Reply Author

    Hi Ahmad,

    Nice work.

    I see that you called this a “boilerplate” with basically means a starting point, right?

    Have you thought about making WPGulp more of a framework that can be extended by a config file and “plugins” much like how WordPress itself is a framework that can extended by plugin? And more importantly, that you never modify the original WordPress code or the original WPGulp code?

    Imagine how less successful WordPress would be if it was simply a boilerplate of code for people to modify instead of a tested and debugged set of versioned code…

    Just yesterday I had a 3-way conversation with a front-end developer we work with, a backend developer who is the author of WPLib Bix and myself (a backend dev) and we were looking into how to add Gulp to WPLib Box. But we want to add Gulp (and anything else) that it will just work “out-of-the-box” (pun intended :) But we still want to give devs the ability to “configure” it for 80+% of use-cases or to replace it for the 20-% use-cases.

    For example with WPGulp, instead of initializing project and projectURL using hardcoded literals, what about loading them from a WPGulp.json file? Further, you could add support for LESS vs. SASS using a configuration option in the same JSON file? Then, over time, as people would ask for enhancements in your GitHub issue tracker you could add more recognized options to the WPGulp.json file.

    You could have a list of “plugins” in WPGulp.json that you could load dynamically. These plugins might be a superset of Node plugins where you could “require” them and also have code to inclue in your named task pipelines.

    We are building an API for WPLib Box that our future admin console and CLI will use, and we want to be able to make those kind of changes via our API and it will be much easier to update a JSON file than to generate code.

    Either we are going to build something like I am describing, or we could include someone else’s Gulp project in WPLib Box, and [collaborating with you](https://ahmadawais.com/my-vision-wordpress-collaboration-over-competition/) to help improve WPGulp looks like a much better route than to build it all ourselves.

    What do you think?

    -Mike


    • Ahmad Awais
      Posted on

      Ahmad Awais Ahmad Awais

      Reply Author

      Hey, Mike!
      Thanks for dropping by. I like the idea and it is needless to say, that I have been looking into making WPGulp more portable. First of all, I went with different branches on Git (that didn’t work well), then I went along Electron and built an app for WPGulp (which is buggy and very basic), later I studied oh-my-zsh (since I am a big fan) and was looking into building something along that line of thought which would be very similar to what you suggested.

      So, yes! Let’s do it. Do you have any idea about how we could go along with something like wpgulpfile.json kind of setup?


      • Mike Schinkel
        Posted on

        Mike Schinkel Mike Schinkel

        Reply Author

        Awesome! I see you are on WordPress Slack; I will reach out to you there.


  • romapad
    Posted on

    romapad romapad

    Reply Author

    Hi! Interesting project! I love to use Sage (from roots.io) for that


    • Ahmad Awais
      Posted on

      Ahmad Awais Ahmad Awais

      Reply Author

      Well, the code you will find in this package is right out of WordPress Core. So, use it with any theme you want.


  • Jamil Ahmed
    Posted on

    Jamil Ahmed Jamil Ahmed

    Reply Author

    I was trying to add more directories for js and css in my project e.g different source and different destination, how I can do that without creating a new task in js. Thanks


    • Ahmad Awais
      Posted on

      Ahmad Awais Ahmad Awais

      Reply Author

      You will need to replicate all the JS based tasks for that. I can’t help you with the limited info you provided me with. I am not sure why you need more directories. You can also edit the JS path variables and add multiple comma separated directories or ignore directories with ! sign. Here’s the syntax for that.


      • Jamil Ahmed
        Posted on

        Jamil Ahmed Jamil Ahmed

        Reply Author

        Let say I have a plugin structure like

        My plugin /
        admin/
        css/
        js/
        assets/
        css/
        js/

        I think in this case I need two different sources for css and js and their destination specifically, so admin css goes to admin folder and assets goes respectively. May be there is another approach.


        • Ahmad Awais
          Posted on

          Ahmad Awais Ahmad Awais

          Reply Author

          Yes, you are right. There can be many ways to do this. You could encapsulated everything in a functions and run it that way for those directories. It is really upto you.


  • Naomi
    Posted on

    Naomi Naomi

    Reply Author

    I can’t seem to make it work with BrowserSync. It seems like it’s not connecting with the right proxy, yet I have it filled in properly. Any tips?

    This is what I get:

    [BS] Proxying: http://localhost
    [BS] Access URLs:
    ————————————————-
    Local: http://localhost:3000/wordpress/
    External: http://192.168.0.105:3000/wordpress/
    ————————————————-
    UI: http://localhost:3001
    UI External: http://192.168.0.105:3001
    ————————————————-


    • Ahmad Awais
      Posted on

      Ahmad Awais Ahmad Awais

      Reply Author

      This exactly how it is supposed to work. You should checkout the docs at BrowserSync. I hope that’d help.


  • kdsou8fsod
    Posted on

    kdsou8fsod kdsou8fsod

    Reply Author

    hello,

    I am trying to figure out how can I use your wp-gulp to optimize my WP development. I wanna to minify js,css files, optimize images, and others cool things. But, it looks that I need a source folder and a dest. folder. If the path of my predefined theme is “wp-content/uploads/2016/03/background-315.jpg”, how can I optimize that image on the fly? can I also minify a js file with path: “wp-content/themes/optimizePressTheme/themes/common.js?ver=2.5.6.1”

    thx you for any advices,


  • Eric Gauvin
    Posted on

    Eric Gauvin Eric Gauvin

    Reply Author

    I’m trying to implement this with underscores. Is it recommended to change the directory structure of underscores? It doesn’t have the the assets structure and custom and vendor for js. Should I create the folder structure shown in the gulpfile?


    • Ahmad Awais
      Posted on

      Ahmad Awais Ahmad Awais

      Reply Author

      Hey, Eric!
      You have two options here, you can either change your gulpfile.js to match the directory structure of your theme, or you can change the directory structure as per the gulpfile. It is pretty highly documented, take a look at it.


  • Jeff
    Posted on

    Jeff Jeff

    Reply Author

    Hi Ahmad,

    Thank you for this amazing boilerplate! I’ve been using it for a month now and I can’t figure out why the BrowserSync auto refresh takes a very long time for PHP and JS changes (~25 seconds).

    SASS changes are – almost – acceptable with ~5sec waiting time.

    Do you have any idea what that could be? I have done a test with https://github.com/BrowserSync/recipes/tree/master/recipes/gulp.sass and it loads very fast – less than 1sec.

    Any help would be highly appreciated.

    Thank you


    • Ahmad Awais
      Posted on

      Ahmad Awais Ahmad Awais

      Reply Author

      @jeff I am going to look into it. Most of the times it is your PC which is slow. If that’s not the case then it is the PHP files check, you can comment that to test if the speed improves.


  • Tiago
    Posted on

    Tiago Tiago

    Reply Author

    Wow! AWESOME Workflow for integrate gulp + WP. Thank you so much for sharing.

    Best!


  • David Stingl
    Posted on

    David Stingl David Stingl

    Reply Author

    Hi Ahmad,

    First of all, let me say thank you! This is very helpful for a noob like me for getting started with Gulp and WordPress. I integrated this into my latest project. Unfortunately, I ran into a little problem while trying to combine WPGulp with the grid-layout engine Susy ( oddbird.net/susy/ ).
    I described the problem here: github.com/oddbird/susy/issues/664
    I think the root of the problem lies in the usage of “gulp-merge-media-queries” what is used by WPGulp. Unfortunately, this one isn’t maintained for years and has in its dependencies still an outdated version of “css-parse”.
    Is there a simple solution for that problem, which you can suggest?
    I saw that there exists already an pull request which might solve the problem: https://github.com/ahmadawais/WPGulp/pull/46
    What do you mean?
    Many thanks in advance for your hints!


    • Ahmad Awais
      Posted on

      Ahmad Awais Ahmad Awais

      Reply Author

      Hey, David! πŸ™Œ
      Thanks for dropping by. That’s very kind of you to say! πŸ’―
      Yes, I have always had issues with the media query merge module and I had plans to remove it altogether. The PR you mentioned was created by a newbie and hence had lots of conflicts. Would you like to refresh the PR or create a new one? I’d be willing to merge it.

      Looking forward!


  • Yuri
    Posted on

    Yuri Yuri

    Reply Author

    Hi! WPGulp is helping me a lot!

    One little question: With the new super awesome WPGulp v2, there is a way to put node_modules in a parent folder?

    I tried this, but doesn’t worked, and I don’t know if this is achivable with the recent changes.

    I work with many small clients, so a unified node_modules folder would help me.

    Thank you very much for this project, and for the time you put back into the community!


    • Ahmad Awais
      Posted on

      Ahmad Awais Ahmad Awais

      Reply Author

      Glad you liked it! πŸ’―
      No never put all modules in one parent folder. That’s a very bad practice. It will mess things up. :P

      Also, kindly find a way to support my open source work? Maybe contribute docs πŸ“–, add a fix πŸ›, new feature πŸ“¦, or go ahead an pay for my time to improve and maintain all this open source software I produce β€” details here β†’


  • Bilal
    Posted on

    Bilal Bilal

    Reply Author

    Hello. Thank you for your project. I got a little problem. “Uncaught TypeError: Cannot set property ‘bootstrap’ of undefined” You can check here: https://vgy.me/hSxoUi.png

    This is my js files: https://vgy.me/QQU2lI.png
    It works good when enqued 1-bootstrap.bundle.js 2-mdb.js

    But when compiled to vendor.js it gives that error. Can you help me please?


  • Avinesh Shakya
    Posted on

    Avinesh Shakya Avinesh Shakya

    Reply Author

    How can i use foundation zurb scss on this?


  • Shah Alom
    Posted on

    Shah Alom Shah Alom

    Reply Author

    Hello Bro,

    Thank You very much for the resourceful foss WPGulp. I want to know is there any command or what are the change require to use WPGulp and react-scripts together in WordPress theme folder or in a plugin folder?