Re-usable Gulp Toolkit for WordPress Themes.
This is a Gulp package which holds all of the tasks, configuration and lint files I use when building WordPress themes. Rather than holding all of these tasks in one giant Gulpfile.js within each theme I build, this is a standalone package and can be pulled in independently.
A more lightweight version of this toolkit is also available for use in WordPress plugins, called Gulp WP Plugin Toolkit.
Using the package is simple - within your custom theme create a package.json which has gulp and gulp-wp-toolkit as dependencies.
Make sure to update the other parts of your package.json too, as these will be pulled in to form the theme stylesheet header
Add a package.json to your theme like so:
{
"name": "craigsimpson",
"homepage": "https://craigsimpson.scot/",
"version": "1.0.0",
"author": "Craig Simpson <craig@craigsimpson.scot>",
"description": "Custom WordPress theme, based on the Genesis Framework.",
"repository": "",
"license": "GPL-2.0",
"main": "Gulpfile.js",
"devDependencies": {
"gulp": "^3.9.1",
"gulp-wp-toolkit": "^2"
}
}
Then create a simple Gulpfile.js in your theme root, like this:
'use strict';
var gulp = require('gulp'),
pkg = require('./package.json'),
toolkit = require('gulp-wp-toolkit');
toolkit.extendConfig({
theme: {
name: "WordPress Theme Name",
homepage: pkg.homepage,
description: pkg.description,
author: pkg.author,
version: pkg.version,
license: pkg.license,
textdomain: pkg.name
},
js: {
'theme' : [
'develop/vendor/a.js',
'develop/js/b.js'
],
'something-conditional' : [
'develop/js/standalone.js'
]
}
});
toolkit.extendTasks(gulp, { /* Task Overrides */ });
Once your Gulpfile.js is in place, install all the dependencies using yarn install. If you're not already using Yarn, please see the installation instructions.
See the files in the example directory for more advanced configuration.
There are also a number of posts on my blog relating to setting up Gulp WP Toolkit, including:
- Adding Gulp WP Toolkit to an existing Genesis theme.
- Gulp WP Toolkit SCSS Configuration and Options
- Gulp WP Toolkit JavaScript Configuration
- Bulk Import Your SCSS Partials using Gulp WP Toolkit
- An Overview of the Gulp WP Toolkit Build Tasks
Once installed, the following tasks will be available to run via gulp <taskname>.
gulp buildruns the following tasks:gulp build:csscompiles SCSS into CSS.gulp build:jsconcatenates JavaScript files defined inconfig.jsand outputs into the theme/js/directory.gulp build:imagesoptimizes all of the images stored in/develop/images/to/images/. If present, yourscreenshot.png(or other file extension) will be automatically output in the theme root.gulp build:i18nruns the following tasks:gulp build:i18npotgengenerates a translations file at/develop/languages/textdomain.pot, where textdomain is the theme package name withinpackage.json.gulp build:potomoconverts and.pofiles within/develop/languages/into.mofiles within/languages/.
gulp build:styleguide(experimental) uses the SCSS files to generate a live style guide at/develop/styleguide/using Cortana (some setup required).gulp build:rtl(experimental) generates an RTL stylesheet in the theme root.
Clean tasks are included so you can quickly remove any compiled assets, for example using gulp clean:js will delete the concatenated .js and .min.js we have built in js/. Tasks available are:
gulp cleanruns the following tasks:gulp clean:csswill delete.cssand.css.mapfiles from the theme root.gulp clean:jswill delete.jsand.min.jsfiles from the/js/output directory.gulp clean:imageswill delete all image files from the/images/output directory.gulp clean:i18nwill delete the generated.potfile within/develop/languages/, and the generated.mofiles within/languages/
gulp lintruns the following tasks:gulp lint:phpruns the following tasks:gulp lint:phpcscheck the code with PHP_CodeSniffer against the WordPress Coding Standards.gulp lint:phpmdcheck the code with PHP Mess Detector.
gulp lint:styleruns the following tasks:gulp lint:scssusesstylelintto check SCSS files against the WordPress Coding Standards.gulp lint:cssusesstylelintto check CSS files against the WordPress Coding Standards.gulp lint:colorschecks colour usage within SCSS files usinggulp-colorguard.
gulp lint:jsruns the following tasks:gulp lint:jsonchecks that any JSON files (for ACF, etc) are valid.gulp lint:jsvalidateruns JSValidate on project JS files..gulp lint:eslintruns ESLint on project JS files.
The default gulp watch task is available and watches the theme (PHP, SCSS, JS, images) for any file changes. On change, the associated build task will be run.
Running gulp serve will launch a new BrowserSync session, proxying the localhost URL which is defined in your theme's config under server -> url key. If the key is not defined, then BrowserSync won't start.
Our gulp watch task will also run, and your browser will live reload when any changes are detected.
BrowserSync can also run independently of gulp watch by running gulp browser-sync.
The default task (gulp) will run gulp build and gulp serve.
Easily bump the version number of your package.json and composer.json files (defined in config) which will in turn bump the version of your theme. Uses Semver.
gulp bumpupdates the patch version. 1.0.0 to 1.0.1gulp bump --patchupdates the patch version. 1.0.0 to 1.0.1gulp bump --minorupdates the minor version. 1.0.0 to 1.1.0gulp bump --majorupdates the major version. 1.0.0 to 2.0.0
The default configuration has all of the source files in a develop directory, in their respective scss, js, images, and languages subdirectories. For new themes, it is recommended to follow this structure, but these paths can be overridden in the config if you prefer or need to work with a different structure.
A typical theme structure may look like:
.
├── develop/
│ ├── images/ (original images)
│ ├── js/ (JavaScript module files)
│ ├── languages/
│ ├── theme-name.pot (generated by Gulp WP Toolkit)
│ └── en_GB.po
│ └── scss/
│ ├── base/ (structure your SCSS how you want)
│ ├── variables/ (structure your SCSS how you want)
│ └── style.scss (reference your SCSS structure here)
├── images/ (generated by Gulp WP Toolkit)
├── js/ (generated by Gulp WP Toolkit)
├── languages/ (generated by Gulp WP Toolkit)
├── node_modules/ (generated by npm / yarn)
├── src/ (PHP classes)
├── templates/ (WP template files)
├── tests/
│ ├── Integration/
│ └── Unit/
├── vendor/ (generated by Composer)
└── views/
Use of gulp-sass-bulk-import means that whole folders of Sass partials can be easily included with @import 'foldername/*';. Using this method, files are loaded in alphabetical order.
If files are required to be loaded in a specific order, you can declare these immediately before the wildcard import with the normal Sass syntax @import 'folder/file'.
This toolkit no longer supports Bower. Better is to add your Bower dependencies into your themes' package.json, and then reference the correct file (from inside your node_modules/) in your style.scss, or the the js config as needed.
All of the existing configuration can be easily overwritten by passing your new config object into the toolkit.extendConfig() function. An example from a recent project shows how easy it is to update the array of JS files to be concatenated, and change the localhost URL to point to your project, for instance.
Additional tasks can be added by passing an object to the toolkit.extendTasks() function, where the key is the name of the task. Example.
You can override any of the lint files contained within this repository by adding a file of the same name in your theme directory. For example, if your theme directory contains a .eslintrc file or phpcs.xml.dist, then it will be automatically used instead of the file included within gulp-wp-toolkit.
Please see CONTRIBUTING.