How to set up Gulp for Compass compilation and minification, JavaScript minification, livereloading, and use with ExpressionEngine.

1) readme.md

How to set up Gulp with an ExpressionEngine project

I freaking love working with technologies like Grunt and Gulp, and wanted to share how to get my current EE front-end workflow set up. With a few tweaks, this can also be used with virtually any other sites (I've used it with Laravel, static sites, Craft, etc).

Install Node.js

• If Node is not yet installed on the machine, it will need to be installed

Install Gulp (if needed)

• If Gulp has never been set up on the machine, the gulp CLI will also need to be installed by running npm install gulp -g

Install Gulp for the project (if needed)

If a package.json file already exists with list of all of the dependencies that Gulp will need for the project, then you can simply switch to the project root directory in the site terminal and run the command npm install. This only needs to happen once so that the dependencies can be downloaded for the project.

If a package.json file does not exist, switch to the project root directory for the site in a terminal. For this configuration, you can install gulp and the needed dependencies using the command npm install gulp gulp-compass gulp-autoprefixer gulp-minify-css gulp-uglify gulp-rename gulp-concat gulp-notify gulp-livereload gulp-plumber --save-dev. You only need to do this once so that the dependencies can be downloaded for the project.

Add the gulp.js file

Copy the gulp.js file (below) to the base of your site. The provided gulp.js file is set up to work with the following project directory structure.

Project Directory Structure

• project root/
  • html/ (web root)
    • css/
    • js/
    • images/
  • src/
    • js/
      • plugins.js
      • site.js
      • [various .js files]
    • scss/
      • [various .scss files]
      • styles.scss
  • system/ (EE system folder)
  • templates/ (EE templates)
  • gulpfile.js
  • package.json (will be added when gulp is installed via CLI)
  • (gulp.png)[https://dl.dropboxusercontent.com/u/12922578/gulp.png]

Start Growl

Make sure Growl is running, as notification will appear in it whenever the browser is livereloaded or whenever there is an error.

Run Gulp

• To just compile the scripts and SCSS one time, simply run the default command gulp. You can also run any of the other task names, like gulp styles.
• To watch the templates, .scss, and .js files for changes, and to automatically compile and minify the relevant files, run the command gulp live. If the livereload browser extensions are installed and enabled, the browser will automatically refresh when any changes are made to style and javascript files in the src directory, or to any template files in the templates directory.

Customize

You can change the title and image that show up in the Growl messages, by editing the notifyInfo object values. :)

2) gulpfile.js

//load plugins
var gulp             = require('gulp'),
	compass          = require('gulp-compass'),
	autoprefixer     = require('gulp-autoprefixer'),
	minifycss        = require('gulp-minify-css'),
	uglify           = require('gulp-uglify'),
	rename           = require('gulp-rename'),
	concat           = require('gulp-concat'),
	notify           = require('gulp-notify'),
	livereload       = require('gulp-livereload'),
	plumber          = require('gulp-plumber'),
	path             = require('path');

//the title and icon that will be used for the Grunt notifications
var notifyInfo = {
	title: 'Gulp',
	icon: path.join(__dirname, 'gulp.png')
};

//error notification settings for plumber
var plumberErrorHandler = { errorHandler: notify.onError({
		title: notifyInfo.title,
		icon: notifyInfo.icon,
		message: "Error: <%= error.message %>"
	})
};

//styles
gulp.task('styles', function() {
	return gulp.src(['src/scss/**/*.scss'])
		.pipe(plumber(plumberErrorHandler))
		.pipe(compass({
			css: 'html/css',
			sass: 'src/scss',
			image: 'html/images'
		}))
		.pipe(autoprefixer('last 2 version', 'safari 5', 'ie 7', 'ie 8', 'ie 9', 'opera 12.1', 'ios 6', 'android 4'))
		.pipe(gulp.dest('html/css'))
		.pipe(rename({ suffix: '.min' }))
		.pipe(minifycss())
		.pipe(gulp.dest('html/css'));
});

//scripts
gulp.task('scripts', function() {
	return gulp.src('src/js/**/*.js')
		.pipe(plumber(plumberErrorHandler))
		.pipe(concat('main.js'))
		.pipe(gulp.dest('html/js'))
		.pipe(rename({ suffix: '.min' }))
		.pipe(uglify())
		.pipe(gulp.dest('html/js'));
});

//watch
gulp.task('live', function() {
	livereload.listen();

	//watch .scss files
	gulp.watch('src/scss/**/*.scss', ['styles']);

	//watch .js files
	gulp.watch('src/js/**/*.js', ['scripts']);

	//reload when a template file, the minified css, or the minified js file changes
	gulp.watch('templates/**/*.html', 'html/css/styles.min.css', 'html/js/main.min.js', function(event) {
		gulp.src(event.path)
			.pipe(plumber())
			.pipe(livereload())
			.pipe(notify({
				title: notifyInfo.title,
				icon: notifyInfo.icon,
				message: event.path.replace(__dirname, '').replace(/\\/g, '/') + ' was ' + event.type + ' and reloaded'
			})
		);
	});
});

3) .gitignore

#node files
/node_modules/*

#sass cache files
.sass-cache

Tried to run this but it says "Task 'default' is not in your gulpfile", anyone has a quick fix for that? I'm really new to gulp. Thanks guys!

@ben-maystreet

To run a default task add it to the file like this:
gulp.task('default', ['live']);

There's one thing when rename is executed I end up with 2 files one without the suffix and the other with the suffix. Am I doing something wrong ?

This gave me an error when I ran "gulp live"

TypeError: Cannot assign to read only property 'mark' of styles.min.css
    at new Gaze (/home/proxima/Desktop/Code/GULP/master-gulp-file/node_modules/gulp/node_modules/vinyl-fs/node_modules/glob-watcher/node_modules/gaze/lib/gaze.js:41:13)
    at gaze (/home/proxima/Desktop/Code/GULP/master-gulp-file/node_modules/gulp/node_modules/vinyl-fs/node_modules/glob-watcher/node_modules/gaze/lib/gaze.js:86:10)
    at Object.module.exports [as watch] (/home/proxima/Desktop/Code/GULP/master-gulp-file/node_modules/gulp/node_modules/vinyl-fs/node_modules/glob-watcher/index.js:12:17)
    at Gulp.watch (/home/proxima/Desktop/Code/GULP/master-gulp-file/node_modules/gulp/index.js:40:14)
    at Gulp.<anonymous> (/home/proxima/Desktop/Code/GULP/master-gulp-file/gulpfile.js:66:8)
    at module.exports (/home/proxima/Desktop/Code/GULP/master-gulp-file/node_modules/gulp/node_modules/orchestrator/lib/runTask.js:34:7)
    at Gulp.Orchestrator._runTask (/home/proxima/Desktop/Code/GULP/master-gulp-file/node_modules/gulp/node_modules/orchestrator/index.js:273:3)
    at Gulp.Orchestrator._runStep (/home/proxima/Desktop/Code/GULP/master-gulp-file/node_modules/gulp/node_modules/orchestrator/index.js:214:10)
    at Gulp.Orchestrator.start (/home/proxima/Desktop/Code/GULP/master-gulp-file/node_modules/gulp/node_modules/orchestrator/index.js:134:8)
    at /usr/local/lib/node_modules/gulp/bin/gulp.js:129:20

I don't know if any one else has this problem but I solved it by just putting the file names in an array and passed it to the watch function

  var files = ['templates/**/*.html', 'html/css/styles.min.css', 'html/js/main.min.js'];
  gulp.watch(files, function(event) {
    ....

original

 gulp.watch('templates/**/*.html', 'html/css/styles.min.css', 'html/js/main.min.js', function(event) {

After following the steps above, I receive this: Error: You need to have Ruby and Compass installed and in your system PATH for this task to work.

@gurujust1n Just came across your comment. gruntjs/grunt-contrib-compass#66 may be of help in sorting out your error message.

awesome

thank a lot. but i run it. i see folder css in scss folder. how do suite i do?

Thanks @pr0x1m4

Thanks! it's useful.