This Gulp article is part of a series created in partnership with SiteGround. Thank you for supporting the partners who make SitePoint possible.
WordPress’ simple theme development is partly responsible for its success. A developer with front-end and PHP knowledge can consult the excellent Codex and get started on their next masterpiece.
Theme development is possible with just a text editor and graphics package, but modern toolsets can revolutionize your workflow. In this tutorial we’ll use Gulp to run tasks including:
Gulp is a JavaScript-based build system which takes your source files and transforms them into optimized versions. If you’re new to Gulp, please refer to An Introduction to Gulp.js for full installation and usage instructions. A summary of the initial steps:
A Gulp (or any) build process requires a set of original source files containing your unmodified code and images. These are processed, manipulated and minified to create build files.
WordPress is installed to a web server folder, perhaps /var/www/ on a Linux/Apache installation. Your WordPress theme must be defined in its own sub-folder within /wp-content/themes/. Therefore, the folder containing our built files could be /var/www/wp-content/themes/mytheme/. At a minimum, themes require two files:
Most themes contain many more files for presenting posts, pages, indexes, categories, tags, and errors. Cross-page partials such as headers and footers are usually defined as are image and JavaScript files.
You could place your source files somewhere within the mytheme folder. That may be useful if you’re distributing a theme to be downloaded, modified and built by others. However, for the purpose of this tutorial, we’re going to use a source folder which is inaccessible from the web server, e.g. ~/mytheme/. The benefits of this approach:
The source project folder requires a further four sub-folders:
From the source folder (~/mytheme/), run the following npm command to install Gulp and all plug-ins as development dependencies:
A node_modules folder will be created which contains the module code. That should be omitted from your source control system (for Git users, add node_modules to your .gitignore file).
Create a new gulpfile.js configuration file in the root of your source folder. Add this code to get started:
We’re defining our default folders, loading modules, then creating a php task to copy new and updated files to the theme folder. The task has been kept intentionally simple to copy the PHP source files as-is.
Save gulpfile.js and create a few .php files in the source template folder. Then enter the following command:
All the files will be copied to the theme folder (/var/www/wp-content/themes/mytheme/).
Image files can often be compressed further using tools such as imagemin. Add the following code to gulpfile.js:
Save then run gulp images. Compressed versions of any new or updated images in the source images folder are copied to /var/www/wp-content/themes/mytheme/images/.
WordPress cannot use Sass files directly; you must compile to a single style.css file. Add the following code to gulpfile.js:
Launch this new task with gulp css to:
The source scss/style.scss file must include the WordPress theme meta data at the top, e.g.
It is important to use /*! as the first line. This ensures the cssnano minifier does not remove the comment and render your theme unusable.
The postcss-assets plugin allows you to refer to image assets using code such as:
You can also inline images with automatic Base64 encoding:
Add the following code to gulpfile.js:
Run this new task with gulp js to:
Rather than calling each task separately, we can add the following code to gulpfile.js:
You can now use gulp build to run the php, js, css and images tasks in parallel. (Note images is a dependency of the css task so we need not call it directly.)
Your workflow can be radically improved by:
First, we need to define a browsersync task in gulpfile.js. This will create a proxy server to your web server running WordPress on localhost (change this domain or use an IP address as necessary):
Now add a watch task to run Browsersync, watch for file changes and run the appropriate task:
Finally, add a default Gulp task which runs an initial build and starts the watch task:
Now run gulp from the command line. The console will display output which includes lines similar to:
Rather than loading your development site from http://localhost/, enter the address http://localhost:3000/ or the External URL if you are viewing from another device. Your WordPress site will load as before but Gulp will watch for changes and apply the updates immediately. You’ll need never switch to your browser and click refresh again!
Hit Ctrl/Cmd + C when you want to stop Gulp processing.
We’ve covered the basics of WordPress theme development with Gulp but there are several thousand plug-ins to aid your workflow. You could consider additional tasks to:
A few hours writing Gulp tasks could save many days of manual processing over the long term.
Gulp is a task runner that automates repetitive tasks in the development process, such as minification, compilation, unit testing, linting, etc. It uses a code-over-configuration approach, making it flexible and easy to use. In WordPress theme development, Gulp can be used to automate tasks like compiling Sass to CSS, optimizing images, and refreshing the browser whenever a file is saved. This significantly speeds up the development process and ensures a smooth workflow.
To install Gulp, you first need to have Node.js and npm installed on your system. Once you have these, you can install Gulp globally by running the command npm install --global gulp-cli in your terminal. After that, navigate to your WordPress theme directory and run npm init to create a package.json file. Finally, install Gulp in your project devDependencies by running npm install --save-dev gulp.
A Gulpfile is a JavaScript file that defines the tasks that Gulp will run. To set up a Gulpfile, create a new file in your theme directory named gulpfile.js. Inside this file, you can define tasks using the gulp.task method. For example, a task to compile Sass to CSS might look like this:

var gulp = require('gulp');
var sass = require('gulp-sass');

gulp.task('sass', function() {
return gulp.src('src/scss/**/*.scss')
.pipe(sass())
.pipe(gulp.dest('dist/css'));
});
Gulp can be used to optimize images using plugins like gulp-imagemin. To do this, first install the plugin by running npm install --save-dev gulp-imagemin. Then, create a task in your Gulpfile to optimize images:

var gulp = require('gulp');
var imagemin = require('gulp-imagemin');

gulp.task('images', function() {
return gulp.src('src/images/**/*')
.pipe(imagemin())
.pipe(gulp.dest('dist/images'));
});
Gulp can be used to automatically refresh the browser using plugins like BrowserSync. To do this, first install BrowserSync by running npm install --save-dev browser-sync. Then, create a task in your Gulpfile to start a BrowserSync server:

var gulp = require('gulp');
var browserSync = require('browser-sync').create();

gulp.task('serve', function() {
browserSync.init({
proxy: 'yourlocal.dev'
});

gulp.watch('src/**/*').on('change', browserSync.reload);
});

Replace ‘yourlocal.dev’ with your local development URL.
Gulp can be used to compile JavaScript files using plugins like gulp-babel. To do this, first install the plugin by running npm install --save-dev gulp-babel @babel/core @babel/preset-env. Then, create a task in your Gulpfile to compile JavaScript:

var gulp = require('gulp');
var babel = require('gulp-babel');

gulp.task('js', function() {
return gulp.src('src/js/**/*.js')
.pipe(babel({
presets: ['@babel/env']
}))
.pipe(gulp.dest('dist/js'));
});
Gulp can be used to minify CSS and JavaScript files using plugins like gulp-clean-css and gulp-uglify. To do this, first install the plugins by running npm install --save-dev gulp-clean-css gulp-uglify. Then, create tasks in your Gulpfile to minify CSS and JavaScript:

var gulp = require('gulp');
var cleanCSS = require('gulp-clean-css');
var uglify = require('gulp-uglify');

gulp.task('minify-css', function() {
return gulp.src('dist/css/**/*.css')
.pipe(cleanCSS())
.pipe(gulp.dest('dist/css'));
});

gulp.task('minify-js', function() {
return gulp.src('dist/js/**/*.js')
.pipe(uglify())
.pipe(gulp.dest('dist/js'));
});
Gulp can be used to lint JavaScript files using plugins like gulp-eslint. To do this, first install the plugin by running npm install --save-dev gulp-eslint. Then, create a task in your Gulpfile to lint JavaScript:

var gulp = require('gulp');
var eslint = require('gulp-eslint');

gulp.task('lint', function() {
return gulp.src('src/js/**/*.js')
.pipe(eslint())
.pipe(eslint.format())
.pipe(eslint.failAfterError());
});
Gulp can be used to run all tasks at once using the gulp.series or gulp.parallel methods. To do this, create a task in your Gulpfile to run all tasks:

var gulp = require('gulp');

gulp.task('default', gulp.series('sass', 'images', 'serve', 'js', 'minify-css', 'minify-js', 'lint'));
Gulp can be used to watch for changes using the gulp.watch method. To do this, create a task in your Gulpfile to watch for changes:

var gulp = require('gulp');

gulp.task('watch', function() {
gulp.watch('src/scss/**/*.scss', gulp.series('sass'));
gulp.watch('src/images/**/*', gulp.series('images'));
gulp.watch('src/js/**/*.js', gulp.series('js', 'lint'));
});
Craig is a freelance UK web consultant who built his first page for IE2.0 in 1995. Since that time he's been advocating standards, accessibility, and best-practice HTML5 techniques. He's created enterprise specifications, websites and online applications for companies and organisations including the UK Parliament, the European Parliament, the Department of Energy & Climate Change, Microsoft, and more. He's written more than 1,000 articles for SitePoint and you can find him @craigbuckler.
© 2000 – 2024 SitePoint Pty. Ltd.
This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.

source