Configuring Gulp to be used with your Bootstrap Starter Kit

There are so many tools out there to use, it's really easy to get distracted and not really know what to use. For a long time I just use Compass to compile my scss files into CSS, but there is so many other things you could be doing too. So when I discovered Gulp, I started to use it, and it helps a lot when I'm theming.

Gulp is a toolkit that helps you automate painful or time-consuming tasks in your development workflow. Integrations are built into all major IDEs and people are using gulp with PHP, .NET, Node.js, Java, and other platforms. I only use a tiny part of Gulp (yet), so be sure to check it out to see it full potentials.

Installing NPM and Gulp (run once on your computer)

Gulp requires node.js, so if you haven't installed it, you can find some information on npmjs website. 

To install Gulp globally on your development workstation (in case you don't have Gulp), you just run (on Mac): npm install --global gulp (some ppl might have to use sudo). 

Gulp Configuration

My Gulp config consists of four different actions:

• Compile scss files into style.css
• Uglify and concat all Javascript files into one .js file
• Minify images in the image folder
• Live reload the page, based on changes of the css, js, twig files in my theme

Since I normally use Bootstrap as my base theme, and Sass Starterkit as the base of my theme, some of the folders are already available in my theme folder. The folders that I create are: lib, js and css. The lib folder is where I store all the JavaScript files that belong to my site. Later, they will be "uglyfied" and concatenated into one file under the js folder. And the output of the sass compile is stored in the css folder.

Of course, if you don't like those names, you can rename it to whatever you like, just remember to change the name of the folders within the gulpfile.js file.

In order to make Gulp run, you need two files, package.json and gulpfile.js Both need to reside at the ROOT of your project. I use a Composer to fetch and install Drupal, so my Drupal code resides inside the web folder of my project.  (Content of the two files are at the bottom of this blog post. )

When you have added the two files to your project, you run npm install to configure your project to use the components in the gulp file. Some vendor specific files will be added to the node_modules folder, so be sure that it's part of the .gitignore file.

Finally, to use this configuration, you only need to run (again, from the root of your project) gulp watch, and Gulp will start "watching" your project for changes. It's like "magic"! (You will have to reload your page manually for the first time to let the autoloader pick up the autoload function). If you don't have a autoloader plugin in your browser, you will have to download and enable it.

Contents of package.json file

{
  "name": "THEME_NAME-gulp",
  "version": "1.0.0",
  "description": "Gulp dependencies for THEME_NAME theme",
  "main": "gulpfile.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "author": "YOUR NAME",
  "license": "ISC",
  "devDependencies": {
    "gulp": "^3.9.1",
    "gulp-autoprefixer": "^3.0.2",
    "gulp-imagemin": "^2.3.0",
    "gulp-sass": "^4.0.2",
    "gulp-sourcemaps": "^2.6.4",
    "gulp-uglify": "^3.0.1",
    "imagemin-pngquant": "^6.0.0"
  }
}

Contents of gulpfile.js

var gulp = require('gulp');
var uglify = require('gulp-uglifyjs');
var sass = require('gulp-sass');
var autoprefixer = require('gulp-autoprefixer');
var sourcemaps = require('gulp-sourcemaps');
var imagemin = require('gulp-imagemin');
var pngquant = require('imagemin-pngquant');

gulp.task('imagemin', function () {
    return gulp.src('./web/themes/custom/THEME_FOLDER/images/*')
        .pipe(imagemin({
            progressive: true,
            svgoPlugins: [{removeViewBox: false}],
            use: [pngquant()]
        }))
        .pipe(gulp.dest('./web/themes/custom/THEME_FOLDER/images'));
});

gulp.task('sass', function () {
  gulp.src('./web/themes/custom/THEME_FOLDER/sass/**/*.scss')
    .pipe(sourcemaps.init())
        .pipe(sass({outputStyle: 'compressed'}).on('error', sass.logError))
        .pipe(autoprefixer('last 2 version', 'safari 5', 'ie 7', 'ie 8', 'ie 9', 'opera 12.1', 'ios 6', 'android 4'))
    .pipe(sourcemaps.write('./'))
    .pipe(gulp.dest('./web/themes/custom/THEME_FOLDER/css'));
});

gulp.task('uglify', function() {
  gulp.src('./web/themes/custom/THEME_FOLDER/lib/*.js')
    .pipe(uglify('main.js'))
    .pipe(gulp.dest('./web/themes/custom/THEME_FOLDER/js'))
});

gulp.task('watch', function(){
    gulp.watch('./web/themes/custom/THEME_FOLDER/sass/**/*.scss', ['sass']);
    gulp.watch('./web/themes/custom/THEME_FOLDER/lib/*.js', ['uglify']);
});