A basic SCSS compilation gulpfile.js

Note: This post is from 2014 and so some links or practices may not be those advised today. It also uses Gulp 3 and so may not work with Gulp 4

This post is not about setting up gulp for the first time - as there are plenty of good blog posts out there explaining that. Instead, this is about getting gulp to compile sass successfully

If you haven't set up gulp, or don't know how, I have compiled a short list of excellent articles at the bottom of the post.

Why would you use gulp to compile sass?

I have only recently required gulp to compile my sass. Before now I was using the built in sass watcher - which served every need. That was, until, I included bootstrap-sass and suddenly my Sass was taking > 5 seconds to compile, which when you are developing is a hell of a long time!

Gulp does some magic and, depending on the file you edit, can take less than a millisecond to compile the css - which is faster than I can press alt + tab and then ctrl + r.

To get to the basic gulpfile, however, was painful. Many of the blog posts are out of date and I struggled to get to where I am (it might just be me though...)

For the below code, I am assuming you understand the basics of gulp and have set it up.

Although the gulpfile below is only for sass compiling, there are a few things put in place for scaling up to handle more functionality for the future.

// Define gulp before we start
var gulp = require('gulp');
// Define Sass and the autoprefixer
var sass = require('gulp-sass');
var prefix = require('gulp-autoprefixer');
// This is an object which defines paths for the styles.
// Can add paths for javascript or images for example
// The folder, files to look for and destination are all required for sass
var paths = {
	styles: {
		src: './app/Admin/assets/sass',
		files: './app/Admin/assets/sass/**/*.scss',
		dest: './public/css/admin'
// A display error function, to format and make custom errors more uniform
// Could be combined with gulp-util or npm colors for nicer output
var displayError = function(error) {
	// Initial building up of the error
	var errorString = '[' + error.plugin + ']';
	errorString += ' ' + error.message.replace("\n",''); // Removes new line at the end
	// If the error contains the filename or line number add it to the string
		errorString += ' in ' + error.fileName;
		errorString += ' on line ' + error.lineNumber;
	// This will output an error like the following:
	// [gulp-sass] error message in file_name on line 1
// Setting up the sass task
gulp.task('sass', function (){
	// Taking the path from the above object
	// Sass options - make the output compressed and add the source map
	// Also pull the include path from the paths object
		outputStyle: 'compressed',
		sourceComments: 'map',
		includePaths : [paths.styles.src]
	// If there is an error, don't stop compiling but use the custom displayError function
	.on('error', function(err){
	// Pass the compiled sass through the prefixer with defined
		'last 2 version', 'safari 5', 'ie 8', 'ie 9', 'opera 12.1', 'ios 6', 'android 4'
	// Funally put the compiled sass into a css file
// This is the default task - which is run when `gulp` is run
// The tasks passed in as an array are run before the tasks within the function
gulp.task('default', ['sass'], function() {
	// Watch the files in the paths object, and when there is a change, fun the functions in the array
	gulp.watch(paths.styles.files, ['sass'])
	// Also when there is a change, display what file was changed, only showing the path after the 'sass folder'
	.on('change', function(evt) {
			'[watcher] File ' + evt.path.replace(/.*(?=sass)/,'') + ' was ' + evt.type + ', compiling...'

The gulpfile and associated package.json can be found as a github gist - feel free to comment/fork. I will keep this simple but updated where necessary.

I have since written a more advanced article - Advanced Gulp File

An introduction to gulp:

and lastly:

View this post on Github

You might also enjoy…

Mike Street

Written by Mike Street

Mike is a CTO and Lead Developer from Brighton, UK. He spends his time writing, cycling and coding. You can find Mike on Mastodon.