Introducing WPGulp: An Easy to Use WordPress Gulp Boilerplate

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 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.

Introducing 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:

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#

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.

	{
	"name" : "WPGulp",
	"author" : "ahmadawais",
	"version" : "1.0.0",
	"license" : "GPL-2.0",
	"repository": {
	"type": "git",
	"url": "https://github.com/ahmadawais/WPGulp"
	},
	"dependencies" : {},
	"devDependencies": {
	"gulp" : "^3.8.11",
	"gulp-autoprefixer" : "^3.1.0",
	"gulp-concat" : "^2.5.2",
	"gulp-notify" : "^2.2.0",
	"gulp-rename" : "^1.2.0",
	"gulp-sass" : "^2.0.0",
	"gulp-sourcemaps" : "^1.5.2",
	"gulp-uglify" : "^1.1.0",
	"gulp-uglifycss" : "^1.0.4"
	}
	}

view raw pacakge.json hosted with by GitHub

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.

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:

• gulp.task Defines your tasks.
• gulp.src Points to the files you want to use i.e. the source.
• gulp.dest Points to the output folder i.e. the destination.
• gulp.watch Helps watch files for changes i.e. File change can trigger a particular task E.g. Change in a CSS file can trigger the styles task.

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.

	/**
	* Configuration.
	*
	* Project Configuration for gulp tasks.
	*
	* Edit the variables as per your project requirements.
	*/
	var project = 'WPGulpTheme'; // Name
	var styleSRC = './assets/css/style.scss'; // Path to main .scss file
	var styleDestination = './'; // Path to place the compiled CSS file
	// Defualt set to root folder
	var jsVendorSRC = './assets/js/vendors/*.js'; // Path to JS vendors folder
	var jsVendorDestination = './assets/js/'; // Path to place the compiled JS vendors file
	var jsVendorFile = 'vendors'; // Compiled JS vendors file name
	// Default set to vendors i.e. vendors.js
	var jsCustomSRC = './assets/js/custom/*.js'; // Path to JS custom scripts folder
	var jsCustomDestination = './assets/js/'; // Path to place the compiled JS custom scripts file
	var jsCustomFile = 'custom'; // Compiled JS custom file name
	// Default set to custom i.e. custom.js
	var styleWatchFiles = './assets/css/**/*.scss'; // Path to all *.scss files inside css folder and inside them
	var vendorJSWatchFiles = './assets/js/vendors/*.js'; // Path to all vendors JS files
	var customJSWatchFiles = './assets/js/custom/*.js'; // Path to all custom JS files

view raw gulpfile.js hosted with by GitHub

#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.

	/**
	* Load Plugins.
	*
	* Load gulp plugins and assign them semantic names.
	*/
	var gulp = require('gulp'); // Gulp of-course
	// CSS related plugins.
	var sass = require('gulp-sass'); // Gulp pluign for Sass compilation
	var autoprefixer = require('gulp-autoprefixer'); // Autoprefixing magic
	var minifycss = require('gulp-uglifycss'); // Minifies CSS files
	// JS related plugins.
	var concat = require('gulp-concat'); // Concatenates JS files
	var uglify = require('gulp-uglify'); // Minifies JS files
	// Utility related plugins.
	var rename = require('gulp-rename'); // Renames files E.g. style.css -> style.min.css
	var sourcemaps = require('gulp-sourcemaps'); // Maps code in a compressed file (E.g. style.css) back to it’s original position in a source file (E.g. structure.scss, which was later combined with other css files to generate style.css)
	var notify = require('gulp-notify'); // Sends message notification to you

view raw gulpfile.js hosted with by GitHub

#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.

	/**
	* Task: styles
	*
	* Compiles Sass, Autoprefixes it and Minifies CSS.
	*
	* This task does the following:
	* 1. Gets the source scss file
	* 2. Compiles Sass to CSS
	* 3. Writes Sourcemaps for it
	* 4. Autoprefixes it and generates style.css
	* 5. Renames the CSS file with suffix .min.css
	* 6. Minifies the CSS file and generates style.min.css
	*/
	gulp.task('styles', function () {
	gulp.src( styleSRC )
	.pipe( sourcemaps.init() )
	.pipe( sass( {
	errLogToConsole: true,
	outputStyle: 'compact',
	//outputStyle: 'compressed',
	// outputStyle: 'nested',
	// outputStyle: 'expanded',
	precision: 10
	} ) )
	.pipe( sourcemaps.write( { includeContent: false } ) )
	.pipe( sourcemaps.init( { loadMaps: true } ) )
	.pipe( autoprefixer(
	'last 2 version',
	'> 1%',
	'safari 5',
	'ie 8',
	'ie 9',
	'opera 12.1',
	'ios 6',
	'android 4' ) )
	.pipe( sourcemaps.write ( styleDestination ) )
	.pipe( gulp.dest( styleDestination ) )
	.pipe( rename( { suffix: '.min' } ) )
	.pipe( minifycss( {
	maxLineLen: 10
	}))
	.pipe( gulp.dest( styleDestination ) )
	.pipe( notify( { message: 'TASK: "styles" Completed!', onLast: true } ) )
	});

view raw gulpfile.js hosted with by GitHub

#4: Task vendorJS#

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

	/**
	* Task: vendorJS
	*
	* Concatenate and uglify vendor JS scripts.
	*
	* This task does the following:
	* 1. Gets the source folder for JS vendor files
	* 2. Concatenates all the files and generates vendors.js
	* 3. Renames the JS file with suffix .min.js
	* 4. Uglifes/Minifies the JS file and generates vendors.min.js
	*/
	gulp.task( 'vendorsJs', function() {
	gulp.src( jsVendorSRC )
	.pipe( concat( jsVendorFile + '.js' ) )
	.pipe( gulp.dest( jsVendorDestination ) )
	.pipe( rename( {
	basename: jsVendorFile,
	suffix: '.min'
	}))
	.pipe( uglify() )
	.pipe( gulp.dest( jsVendorDestination ) )
	.pipe( notify( { message: 'TASK: "vendorsJs" Completed!', onLast: true } ) );
	});

view raw gulpfile.js hosted with by GitHub

#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.

	/**
	* Task: customJS
	*
	* Concatenate and uglify custom JS scripts.
	*
	* This task does the following:
	* 1. Gets the source folder for JS custom files
	* 2. Concatenates all the files and generates custom.js
	* 3. Renames the JS file with suffix .min.js
	* 4. Uglifes/Minifies the JS file and generates custom.min.js
	*/
	gulp.task( 'customJS', function() {
	gulp.src( jsCustomSRC )
	.pipe( concat( jsCustomFile + '.js' ) )
	.pipe( gulp.dest( jsCustomDestination ) )
	.pipe( rename( {
	basename: jsCustomFile,
	suffix: '.min'
	}))
	.pipe( uglify() )
	.pipe( gulp.dest( jsCustomDestination ) )
	.pipe( notify( { message: 'TASK: "customJs" Completed!', onLast: true } ) );
	});

view raw gulpfile.js hosted with by GitHub

#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.

	/**
	* Watch Tasks.
	*
	* Watches for file changes and runs specific tasks.
	*/
	gulp.task( 'default', [ 'styles', 'vendorsJs', 'customJS' ], function () {
	gulp.watch( './assets/css/**/*.scss', [ 'styles' ] );
	gulp.watch( './assets/js/vendors/*.js', [ 'vendorsJs' ] );
	gulp.watch( './assets/js/custom/*.js', [ 'customJS' ] );
	});

view raw gulpfile.js hosted with by GitHub

That’s all there is.

The Complete Code of gulpfile.js#

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

	/**
	* Gulpfile.
	*
	* A simple implementation of Gulp.
	*
	* Implements:
	* 1. Sass to CSS conversion
	* 2. JS concatenation
	* 3. Watch files
	*
	* @since 1.0.0
	* @author Ahmad Awais (@mrahmadawais)
	*/
	/**
	* Configuration.
	*
	* Project Configuration for gulp tasks.
	*
	* Edit the variables as per your project requirements.
	*/
	var project = 'WPGulpTheme'; // Name
	var styleSRC = './assets/css/style.scss'; // Path to main .scss file
	var styleDestination = './'; // Path to place the compiled CSS file
	// Defualt set to root folder
	var jsVendorSRC = './assets/js/vendors/*.js'; // Path to JS vendors folder
	var jsVendorDestination = './assets/js/'; // Path to place the compiled JS vendors file
	var jsVendorFile = 'vendors'; // Compiled JS vendors file name
	// Default set to vendors i.e. vendors.js
	var jsCustomSRC = './assets/js/custom/*.js'; // Path to JS custom scripts folder
	var jsCustomDestination = './assets/js/'; // Path to place the compiled JS custom scripts file
	var jsCustomFile = 'custom'; // Compiled JS custom file name
	// Default set to custom i.e. custom.js
	var styleWatchFiles = './assets/css/**/*.scss'; // Path to all *.scss files inside css folder and inside them
	var vendorJSWatchFiles = './assets/js/vendors/*.js'; // Path to all vendors JS files
	var customJSWatchFiles = './assets/js/custom/*.js'; // Path to all custom JS files
	/**
	* Load Plugins.
	*
	* Load gulp plugins and assing them semantic names.
	*/
	var gulp = require('gulp'); // Gulp of-course
	// CSS related plugins.
	var sass = require('gulp-sass'); // Gulp pluign for Sass compilation
	var autoprefixer = require('gulp-autoprefixer'); // Autoprefixing magic
	var minifycss = require('gulp-uglifycss'); // Minifies CSS files
	// JS related plugins.
	var concat = require('gulp-concat'); // Concatenates JS files
	var uglify = require('gulp-uglify'); // Minifies JS files
	// Utility related plugins.
	var rename = require('gulp-rename'); // Renames files E.g. style.css -> style.min.css
	var sourcemaps = require('gulp-sourcemaps'); // Maps code in a compressed file (E.g. style.css) back to it’s original position in a source file (E.g. structure.scss, which was later combined with other css files to generate style.css)
	var notify = require('gulp-notify'); // Sends message notification to you
	/**
	* Task: styles
	*
	* Compiles Sass, Autoprefixes it and Minifies CSS.
	*
	* This task does the following:
	* 1. Gets the source scss file
	* 2. Compiles Sass to CSS
	* 3. Writes Sourcemaps for it
	* 4. Autoprefixes it and generates style.css
	* 5. Renames the CSS file with suffix .min.css
	* 6. Minifies the CSS file and generates style.min.css
	*/
	gulp.task('styles', function () {
	gulp.src( styleSRC )
	.pipe( sourcemaps.init() )
	.pipe( sass( {
	errLogToConsole: true,
	outputStyle: 'compact',
	//outputStyle: 'compressed',
	// outputStyle: 'nested',
	// outputStyle: 'expanded',
	precision: 10
	} ) )
	.pipe( sourcemaps.write( { includeContent: false } ) )
	.pipe( sourcemaps.init( { loadMaps: true } ) )
	.pipe( autoprefixer(
	'last 2 version',
	'> 1%',
	'safari 5',
	'ie 8',
	'ie 9',
	'opera 12.1',
	'ios 6',
	'android 4' ) )
	.pipe( sourcemaps.write ( styleDestination ) )
	.pipe( gulp.dest( styleDestination ) )
	.pipe( rename( { suffix: '.min' } ) )
	.pipe( minifycss( {
	maxLineLen: 10
	}))
	.pipe( gulp.dest( styleDestination ) )
	.pipe( notify( { message: 'TASK: "styles" Completed!', onLast: true } ) )
	});
	/**
	* Task: vendorJS
	*
	* Concatenate and uglify vendor JS scripts.
	*
	* This task does the following:
	* 1. Gets the source folder for JS vendor files
	* 2. Concatenates all the files and generates vendors.js
	* 3. Renames the JS file with suffix .min.js
	* 4. Uglifes/Minifies the JS file and generates vendors.min.js
	*/
	gulp.task( 'vendorsJs', function() {
	gulp.src( jsVendorSRC )
	.pipe( concat( jsVendorFile + '.js' ) )
	.pipe( gulp.dest( jsVendorDestination ) )
	.pipe( rename( {
	basename: jsVendorFile,
	suffix: '.min'
	}))
	.pipe( uglify() )
	.pipe( gulp.dest( jsVendorDestination ) )
	.pipe( notify( { message: 'TASK: "vendorsJs" Completed!', onLast: true } ) );
	});
	/**
	* Task: customJS
	*
	* Concatenate and uglify custom JS scripts.
	*
	* This task does the following:
	* 1. Gets the source folder for JS custom files
	* 2. Concatenates all the files and generates custom.js
	* 3. Renames the JS file with suffix .min.js
	* 4. Uglifes/Minifies the JS file and generates custom.min.js
	*/
	gulp.task( 'customJS', function() {
	gulp.src( jsCustomSRC )
	.pipe( concat( jsCustomFile + '.js' ) )
	.pipe( gulp.dest( jsCustomDestination ) )
	.pipe( rename( {
	basename: jsCustomFile,
	suffix: '.min'
	}))
	.pipe( uglify() )
	.pipe( gulp.dest( jsCustomDestination ) )
	.pipe( notify( { message: 'TASK: "customJs" Completed!', onLast: true } ) );
	});
	/**
	* Watch Tasks.
	*
	* Watches for file changes and runs specific tasks.
	*/
	gulp.task( 'default', [ 'styles', 'vendorsJs', 'customJS' ], function () {
	gulp.watch( styleWatchFiles, [ 'styles' ] );
	gulp.watch( vendorJSWatchFiles, [ 'vendorsJs' ] );
	gulp.watch( customJSWatchFiles, [ 'customJS' ] );
	});

view raw gulpfile.js hosted with by GitHub

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:

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: Gulp WordPress Boilerplate.
• WPGulpTheme: You can check a demo WordPress theme implementation with WPGulp.
• My Advanced Gulp Workflow for WordPress Themes

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 →