Gulp

Introduction

Gulp is our preferred tool for task running (for the frontend). 9 times out of 10, it is handling SCSS and hooks in Browsersync for easier editing and real time feedback of changes in the browser.

Prerequisites

You will need a stable version of NodeJS and NPM to use Gulp. See here for installation of NodeJS/Node

Installation

  • Install gulp with npm
    1
    npm install --global gulp-cli
    

We use the global flag so we can run gulp from any where, you may need to be root or use sudo to do a global install.

  • Install Dependencies for gulp
    1
    2
    3
    4
    # This should be where you're gulpfile and package.json file is located.
    cd $WEBROOT
    # Installs dependencies for gulpfile from the package.json.
    npm install
    

Quick Start

When gulp is run from the command line, it will search for a gulpfile.js in the current working directory. If it does not find it, it will throw an error and exit.

However when the file is present it will run the default task. This guide does not cover writing gulp files themselves, see the official gulp documentation or platform specific documentation.

Each task will describe a certain set of actions, top level tasks can be invoked by passing their names in to gulp.

1
gulp dosomething

You can look at the available tasks by opening gulpfile.js. A task follows the signature

1
2
3
gulp.task( 'compilethings', function() {
    // ... Compilation steps happen here
});

This would be called with.

1
gulp compilethings

A gulp file uses Node so you can use import with packages installed via npm

Simple Compile Sass(Scss)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
//Dependencies
let gulp = require('gulp');
let sass = require('gulp-sass');
let cleanCss = require('gulp-clean-css');
let sourcemaps = require('gulp-sourcemaps');
let uglify = require('gulp-uglify');

//Config
let themeDir = "yourThemeDirectory/";
let src = {
    scss: themeDir + '/scssFolder/*.scss',
    css: themeDir + '/cssFolder'
};

gulp.task('sass:watch', function() {
    gulp.watch(src.scss, ['sass']);
});

/**
 * Compile sass, filter the results
 */
gulp.task('sass', function () {
    return gulp.src(src.scss)
        .pipe(sourcemaps.init())
        .pipe(sass().on('error', sass.logError))
        .pipe(cleanCss({
            level: 2
        }))
        .pipe(sourcemaps.write('./'))
        .pipe(gulp.dest(src.css));
});

gulp.task('default', ['sass']);

Errors on Sass Compilation

If you are recieving an error related to an incorrect binding/downloading error on node-sass try the following: First try updating to the latest Gulp Sass