Blog / Articles, Useful tools

A quick guide to Gulp

Gulp is a tool that helps you with several tasks when it comes to web development. What this means, is that it can handle most of the time-consuming tasks for you.

For example

  • it can help you compile SASS & SCSS into CSS,
  • concatenate & minify your javascript files,
  • optimize your images & SVGs
  • create favicons
  • Convert SVGs to PNGs
  • Generate images at different sizes.
  • Combine SVGs into one
  • and many other things

To start using Gulp, you will need to install node.js

Then you can install gulp by running the following command in your terminal:

npm install gulp -g

This only needs to be done once.

There is an excellent intro guide here:

Gulp for Beginners

TO START A NEW PROJECT USING GULP

For Every project where you need to add gulp You can follow the steps below:

  1. Create & place the package.json file in the root of your project or WordPress theme. An example of this file:
{
   "name": "THEME NAME",
   "author": "your name",
   "devDependencies": {
      "del": "latest",
      "gulp": "latest",
      "gulp-compass": "latest",
      "gulp-concat": "latest",
      "gulp-image": "latest",
      "gulp-rename": "latest",
      "gulp-uglify": "latest",
      "pump": "latest"
   },
   "dependencies": {}
}

Just replace “Theme name” And “your name” with your project details.

2. In the same folder, create & add the gulpfile.js

For starters, you can only have the following contents:

var gulp = require('gulp');

The contents of this file are written in javascript.

To install gulp for your project, open up your terminal and go to the folder where you placed the files above.

eg cd htdocs\your_project

then you run the following command:

npm install gulp --save-dev

So now, you have Gulp installed for your project.

GULP IS A TASK MANAGER

For every task, you will need to install the appropriate plugin and then create the gulp task in gulpfile.js.

EXAMPLE: COMBINE & MINIFY YOUR JAVASCRIPT FILES:

Install the needed plugins by running the commands in your terminal:

npm install gulp-concat --save-dev
npm install gulp-uglify --save-dev
npm install --save-dev pump

or in just one line:

npm install --save-dev gulp-concat gulp-uglify pump

Then, you just create the gulp task in gulpfile.js

var concat = require('gulp-concat'),
 uglify = require('gulp-uglify'),
 pump = require('pump');

//============ concatenate & minify JS files
//gulp js

gulp.task('js', function (cb) {
    pump([
        gulp.src(['js/blankshield.min.js', 'js/hammer.min.js', 'js/TweenMax.min.js', 'js/jquery-gsapSlider.min.js', 'js/functions.js', 'js/main.js']),
        //or gulp.src('js/*.js'),
        uglify(),
        concat('app.min.1.0.1.js'),   //### VERSIONING HERE!!!
        gulp.dest('js')
    ], cb);
    //pump notifies for errors
});

Now, to run this task, you simply type the below command in your terminal:

gulp js

EXAMPLE: USE COMPASS AS YOUR CSS COMPILER

install the needed plugins by running the below commands in your terminal:

npm install gulp-compass --save-dev 
npm install gulp-rename --save-dev 
npm install --save-dev del

or just in one line:

npm install --save-dev gulp-compass gulp-rename del

Then you can create the gulp task in gulpfile.js:

//create a variable for each plugin
var compass = require('gulp-compass'),
    rename = require("gulp-rename"),
    del = require('del');

//create a task to compile Compass to CSS.
//it checks every scss file in the main folder and makes the compilation according to the config.rb file
//we need to keep versioning of the css file generated, so we rename the generated main.css file to main.v.1.0.1.css and place it inside the css folder

gulp.task('run_compass', function() {
    return gulp.src('./styles/main/*.scss')
        .pipe(compass({
            config_file: './styles/config.rb',
            css: 'styles/css',
            sass: 'styles/main'
        }))
        .pipe(rename("main.v.1.0.1.css"))       //### VERSIONING HERE!!!
        .pipe(gulp.dest('styles/css'));
});

//By default the main.css file will be created, but not deleted after the versioning done above.
//To delete it we make another task that will first run_compass and then delete the unstaged main.css file

gulp.task('compass', ['run_compass'], function () {
    return del(['styles/css/main.css']);
});

Now, to compile your css you type the following on the command line:

gulp compass

THE COMPLETE GULPFILE.JS TO COMPILE COMPASS, MINIFY JS, OPTIMIZE IMAGES AND GENERATE A FAVICON BECOMES:

var gulp = require('gulp');

var compass = require('gulp-compass'),
    rename = require("gulp-rename"),
    concat = require('gulp-concat'),
    uglify = require('gulp-uglify'),
    pump = require('pump'),
    image = require('gulp-image'),
    del = require('del');

var realFavicon = require ('gulp-real-favicon');
var fs = require('fs');


//============ Compass
//gulp compass

gulp.task('run_compass', function() {
    return gulp.src('./styles/main/*.scss')
        .pipe(compass({
            config_file: './styles/config.rb',
            css: 'styles/css',
            sass: 'styles/main'
            //import_path
        }))
        .pipe(rename("main.v.1.0.1.css"))       //### VERSIONING HERE!!!
        .pipe(gulp.dest('styles/css'));
});

gulp.task('compass', ['run_compass'], function () {
    //first run_compass and then delete the unstaged css file
    return del(['styles/css/main.css']);
});

//============ concatenate & minify JS files
//gulp js

gulp.task('js', function (cb) {
    pump([
        gulp.src(['js/blankshield.min.js', 'js/hammer.min.js', 'js/TweenMax.min.js', 'js/jquery-gsapSlider.min.js', 'js/functions.js', 'js/main.js']),
        //or gulp.src('js/*.js'),
        uglify(),
        concat('app.min.1.0.1.js'),   //### VERSIONING HERE!!!
        gulp.dest('js')
    ], cb);
    //pump notifies for errors
});

//=========== optimize images
//gulp images

gulp.task('images', function () {
    gulp.src('./images/*.{jpg,png,jpeg,gif}')
        .pipe(image({
            pngquant: true,
            optipng: true,
            zopflipng: false,
            jpegRecompress: true,
            mozjpeg: true,
            guetzli: false,
            gifsicle: true,
            svgo: false,
            concurrent: 10
        }))
        .pipe(gulp.dest('./images'));
});


//========== Create Favicon
//gulp generate-favicon
//after, you should update the theme color in header.php of your theme

// File where the favicon markups are stored
var FAVICON_DATA_FILE = 'faviconData.json';

var favicon_settings = {
    project_name: 'Your Project',
    logo_260x260_path: 'images/favicon.png',   //a png of 260 x 260px
    generated_favicons_destination: '../../../',
    favicon_background_color: '#ffffff',
    theme_color: '#30b1de'
};

// Generate the icons. This task takes a few seconds to complete.
// You should run it at least once to create the icons. Then,
// you should run it whenever RealFaviconGenerator updates its
// package (see the check-for-favicon-update task below).
gulp.task('generate-favicon', function(done) {
    realFavicon.generateFavicon({
        masterPicture: favicon_settings.logo_260x260_path,
        dest: favicon_settings.generated_favicons_destination,
        iconsPath: '/',
        design: {
            ios: {
                pictureAspect: 'backgroundAndMargin',
                backgroundColor: favicon_settings.favicon_background_color,
                margin: '14%',
                assets: {
                    ios6AndPriorIcons: false,
                    ios7AndLaterIcons: true,
                    precomposedIcons: false,
                    declareOnlyDefaultIcon: true
                }
            },
            desktopBrowser: {},
            windows: {
                pictureAspect: 'whiteSilhouette',
                backgroundColor: favicon_settings.theme_color,
                onConflict: 'override',
                assets: {
                    windows80Ie10Tile: false,
                    windows10Ie11EdgeTiles: {
                        small: false,
                        medium: true,
                        big: false,
                        rectangle: false
                    }
                }
            },
            androidChrome: {
                pictureAspect: 'noChange',
                themeColor: favicon_settings.theme_color,
                manifest: {
                    name: favicon_settings.project_name,
                    display: 'browser',
                    orientation: 'notSet',
                    onConflict: 'override',
                    declared: true
                },
                assets: {
                    legacyIcon: false,
                    lowResolutionIcons: false
                }
            },
            safariPinnedTab: {
                pictureAspect: 'silhouette',
                themeColor: favicon_settings.theme_color
            }
        },
        settings: {
            compression: 3,
            scalingAlgorithm: 'Mitchell',
            errorOnImageTooSmall: false
        },
        markupFile: FAVICON_DATA_FILE
    }, function() {
        done();
    });
});

//=========== WATCH any change and run specified task
//gulp watch

gulp.task('watch', function() {
    gulp.watch('js/*.js', ['js']);
    gulp.watch('images/**', ['images']);
    gulp.watch(['styles/main/*.scss', 'styles/partials/*.scss', 'styles/vendor/*.scss'], ['compass']);
});

//====== WATCH ONLY for css changes
//gulp watch:css

gulp.task('watch:css', function() {
    gulp.watch(['styles/main/*.scss', 'styles/partials/*.scss', 'styles/vendor/*.scss'], ['compass']);
});

//============ run ALL tasks once
//gulp

gulp.task('default', ['compass', 'js', 'images']);

 

Here you may find an extensive list of Gulp resources, plugins, and boilerplates for a better development workflow automation

RELATED ARTICLES
VIEW ALL ARTICLES