Basic modular gulp setup for use in WordPress theme development.

This is the basic modular gulp starter setup that is used for wpdevelopersclub.com courses.

• Contributors: Alain Schlesser
• License: GPL-2.0+

Features

General

• Modular structure that is easy to extend, with each task in a separate file.
• Single configuration file that allows a quick adaptation to the folder structure of a project.
• Error handling that pops up notifications and keeps the watch task running on error.

Styles

• Linting through Stylelint with WordPress standards preconfigured (overrideable in config.js).
• Compilation of Sass styles with libSass.
• Post-processing through PostCSS. Plugins included by default:
  • Autoprefixer to add browser vendor prefixes;
  • CSS-MQPacker to regroup media queries;
  • Perfectionist to prettify generated CSS.
• Check browser support of generated CSS against Autoprefixer settings through doiuse.
• Minification through cssnano (both minified & non-minified version are usable).
• Sourcemaps for easy debugging provided by gulp-sourcemaps.

Scripts

• Linting through JSHint with WordPress standards preconfigured.
• Minification through UglifyJS (both minified & non-minified version are usable).

Images

• Optimization through ImageMin.

Requirements

The main requirements to be able to use this are:

• Node.js - tested with 2.11.3
• gulp - tested with 3.9

Installation

The contents of this repository are meant to be dropped inside the root folder of an existing project, so that the gulpfile.js resides at the root of the project.

The file gulp/config.js should be modified so that it fits the project's folder structure.

To add the dependencies that are needed for the individual gulp tasks to your project's package.json (which should already exist), run the following command in your project's root folder:

cat gulp/dependencies | xargs npm install --save-dev

The file gulp/dependencies can be safely deleted after this operation, it is no longer needed.

Usage

To get an overview of the available tasks that are provided with this starter setup, run the following command in your project's root folder:

gulp help

The default task that will run when no specific option is provided is the watch task.

Special Notes

style.css

The stylesheet gets compiled to a style.css & style.min.css, but they do not get moved to the theme root folder.

Although WordPress requires a file called style.css inside the theme root folder, this goes against several best practices. That's why this setup will provide both minified & non-minified versions of the stylesheet in the proper assets folder (defaults to assets/styles/style.css).

You should provide a stub file inside the theme's root folder with the necessary theme metadata comments, so that WordPress correctly recognizes the theme.

To load the correct stylesheet on the frontend, add the following code to your theme:

add_filter( 'stylesheet_uri', 'wpdc_stylesheet_uri', 10, 2 );
/**
 * Modify location of main stylesheet
 * N.B.: style.css in the theme's root is still needed to provide WordPress
 * with the necessary metadata about the theme
 */
function wpdc_stylesheet_uri( $stylesheet_uri, $stylesheet_dir_uri ) {

	// TODO: Adapt this to your theme's folder structure
	$folder = '/assets/styles/';

	// TODO: Adapt this to your theme's filenames
	$name = 'style';

	$suffix = defined( SCRIPT_DEBUG ) ? '.css' : '.min.css';

	return $stylesheet_dir_uri . $folder . $name . $suffix;
}

Known Issues

• gulp dist has not been completed yet.

• There currently seems to be a race condition between Sass & PostCSS. Thanks to @iCaspar for the testing & debugging.

• If you are getting errors while pulling in the dependencies as described in the section "Installation", make sure that you are running a current version of npm. The latest stable one should always be correct, as of this writing, the code has been tested with version 3.3.9. To get the current version, type the command npm -v at your command-line. It is also a good idea to clear your npm's cache, as it might contain old versions of the packages we're trying to use. To clear your cache, type npm cache clean at your command-line.