How to use PostCSS, SASS and Gulp in WordPress Theme Development

WordPress has been changing fast, especially with Gutenberg editor, more bleeding edge technologies will be used in WordPress theme and plugin development. Many of you are using CSS pre-processor like Sass, CSS compiler like PostCSS with WordPress theme and plugin development. But with the right task runner like – Gulp, you can combine Sass and PostCSS. For beginners who are not using any of these CSS awesomeness, let me state the benefits of combing both Sass and PostCSS with task runner –

1. Use Sass CSS variables as well as CSS native variables at the same time
2. Automatically add browser vendor prefixes
3. Use CSS4 syntax with browser support
4.  Get all the features of Sass and PostCSS in a single stylesheet

Why use Gulp?

Man, why are you complicating my development workflow? I hear you. But believe me, once you get the hold off it you’ll never go back to your old ways. Also, Gulp is –

• Easier to understand
• Gulp use JS syntax unlike JSON syntax
• Gulp config code is easy to read and maintain
• Sass to PostCSS to native CSS conversion
• Watch files for changes
• Automatically refresh browser tab each time you save file change

Now let’s dive into the configuration steps.

Step 0 # Install Node

P.S. I’m a Windows 7 user, and all these configurations are meant for a Windows user. But I’m sure you can find more info about Linux based setup online. For Mac configuration you can follow this Introducing WPGulp: An Easy to Use WordPress Gulp Boilerplate by Ahmad Awais

I will be using Windows 7 operating system but the build process is almost same for Win 10 or MacOS users. First you need to install Node –

1. Node, Download from here – https://nodejs.org/en/
2. Git, Download link – https://git-scm.com/download/win

MacOS has git build right into it, so Apple users don’t have to install Git. Once installed, open up your command prompt ( Go to start and search “command prompt”)

Open the terminal and enter to check successful node installation:

node -v

Installed Node.js version number will be displayed.

Step 1 # Go Theme Directory

You need to be in your theme directory via command line before setting up config. In order to that, type cd press space-bar and drag and drop the folder into your command prompt window and press enter. For example – If your theme name is “One” drag and drop the folder into the command prompt window and press enter.

In case you didn’t know, cd means change directory. What you are doing is changing your command prompt folder directory to the theme or plugin directory.

Step 2 # Create package.json file

Once inside your theme folder, type npm init and it would initiate npm pacakge and ask few information regarding your project. You can keep the file name index.js but I prefer to rename it to  to gulpfile.js. This will ask you a few questions about your project and ultimately generate you a package.json file, which lists dependencies and stores core information about your project.

Step 3 # Install Gulp

In the command prompt window type –

npm install gulp -g

the -g stands for global. It means Gulp is installed globally. Verify Gulp install by typing

gulp -v

it will show the gulp version installed in your directory. Here’s a my gulpfile code –

{
 "name": "theme name",
 "version": "1.0.0",
 "description": "project description",
 "main": "gulpfile.js",
 "scripts": {
 "test": "echo \"Error: no test specified\" && exit 1"
 },
 "author": "Ashiq",
 "license": "ISC",
 "dependencies": {
 "gulp": "^3.9.1",
 }
}

Up until now, apart from Gulp there’s zero dependencies installed.

Step 4 # Install Dependencies

After installing gulp on your WordPress theme folder, you need to install few dependencies to make the whole SASS and PostCSS thing work. type –

npm install gulp-postcss gulp-sass postcss-cssnext gulp-notify gulp-livereload --save -dev

Now let’s break it down –

• Gulp PostCSS – installs PostCSS for gulp
• Gulp SASS – installs SASS for gulp
• PostCSS- CSSNext – installs CSS Next plugin for PostCSS for gulp. This means you can use CSS4 syntax like CSS native variables along with some cool next level features. For full CSSNext features check out this page – http://cssnext.io/features/
  • Note: Install postcss-preset-env , CSSNext project has been abounded by the creator.
• Gulp Notify – installs notification system for each successful CSS compilation
• Gulp Livereload – Why refresh browser manually when you can automate! This plugin can reload the browser automatically whenever you save your CSS file. You also need to install browser extension for that ( For Chrome – https://chrome.google.com/webstore/detail/livereload/jnihajbhpnppcggbcgedagnkighmdlei )

--save -dev   is use to save the package for development purpose. Example: unit tests, minification etc.

Once installed, your package.json file would look like this –

{ 
"name": "theme name", 
"version": "1.0.0", 
"description": "project description", 
"main": "gulpfile.js",
 "scripts": { 
"test": "echo \"Error: no test specified\" && exit 1" },
 "author": "Ashiq", 
"license": "ISC", 
"dependencies": { 
"gulp": "^3.9.1", 
"gulp-livereload": "^3.8.1",
 "gulp-notify": "^3.2.0",
 "gulp-postcss": "^7.0.1",
 "gulp-sass": "^4.0.1", 
"postcss-cssnext": "^3.1.0", } 
}

Step 5 # How Gulp Works

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.

Step 6 # Configure Gulp tasks

gulpfile.js is where automated tasks are written. After installing, first you require the installed packages and then assign it to a variable and later call them in different gulp functions to make the magic happen. Go to gulpfile.js and paste this code –

var gulp = require('gulp');
var postcss = require('gulp-postcss');
var sass = require('gulp-sass');
var cssnext = require('postcss-cssnext');
var notify = require('gulp-notify');
var livereload = require('gulp-livereload');

I just declared and assigned packages to variables. Now, copy and paste below codes

gulp.task('styles', function () {
 var processors = [
 cssnext({})
 ];


return gulp.src('style.scss')
 .pipe(sass())
 .pipe(postcss(processors))
 .pipe(purge())
 .pipe(notify("success"))
 .pipe(gulp.dest('.'))
 .pipe(livereload());
});

Gulp task is set to run through cssnext pre-processors and then we are piping our gulp plugins one by one to sequentially run. First we are making sure that the sass package gets picked and processed and output by gulp. Then it gets to run through PostCSS package, including all the PostCSS processors we added earlier. Once, these steps are done a notification will pop up on your windows task bar. In my case, I will get “success”. You can change the notification message to anything you like. Next the file will be output in specified directory, in my case I’m outputting the file in project root directory.

This is the flow of the entire process but it will not work until you added your watch command. Copy and paste below codes –

gulp.task('watch:styles', function () {
 livereload.listen();
 gulp.watch('**/*.scss', ['styles']);
});

Now, I’m telling gulp to watch any files with .scss extension to watch and run the function and output file in the specified directory. Type and enter –

gulp styles

If everything goes right, you will get “success” notification popping up in your taskbar.  Typing gulp styles will give you one time compile and notification. Typing the same command repeatedly doesn’t make sense. To automate the process type and press enter –

gulp watch:styles

it will run the entire process every time you save your sass file. Now, you need to reload the browser tab with every sass file save. Download this  browser extension , make sure you check in the “Allow access to file URLs” from the extension option. Enable “LiveReload” and Reload the index.html in the browser, and we’re done.

The full gulpfile.js code will look like this –

var gulp = require('gulp');
var postcss = require('gulp-postcss');
var sass = require('gulp-sass');
var cssnext = require('postcss-cssnext');
var notify = require('gulp-notify');
var livereload = require('gulp-livereload');

gulp.task('styles', function () {
var processors = [
cssnext({})
];

return gulp.src('style.scss')
.pipe(sass())
.pipe(postcss(processors))
.pipe(notify("success"))
.pipe(gulp.dest('.'))
.pipe(livereload());
});


gulp.task('watch:styles', function () {
livereload.listen();
gulp.watch('**/*.scss', ['styles']);
});

and the full package.json file code will look like this –

{
"name": "theme_name",
"version": "1.0.0",
"description": "Lorem ipsum dolor",
"main": "gulpfile.js",
"scripts": {
"test": "echo \"Error: no test specified\" && exit 1"
},
"author": "Ashiq",
"license": "ISC",
"dependencies": {
"gulp": "^3.9.1",
"gulp-livereload": "^3.8.1",
"gulp-notify": "^3.2.0",
"gulp-postcss": "^7.0.1",
"gulp-sass": "^4.0.1",
"postcss-cssnext": "^3.1.0",
}
}

I hope, this WordPress gulp tutorial will help you to use Sass postcss and Gulp in our WordPress theme development. WordPress gulp combining with liverreload with supercharge your development workflow. I believe now you can use sass and PostCSS in WordPress theme development easily.