Compiling SASS/SCSS to CSS with Gulp

This tutorial is part of a series on Gulp:

• Getting Started with Gulp Javascript Task Runner
• Compiling SASS/SCSS to CSS with Gulp
• Concatenate & Minify Javascript with Gulp, Improve Site Performance

Once you have installed Gulp and understand the basics of creating tasks, you can start using Gulp to do real work! (If you need help installing Gulp, go back and read Getting Started with Gulp Javascript Task Runner.) In this tutorial we will use Gulp to compile SASS, SCSS or LESS to CSS, watch our files, and recompile them any time changes are detected. I'm using SCSS in this tutorial so, first, I installed gulp-sass.

npm install gulp-sass --save-dev

Note: I tried using gulp-ruby-sass at first but I could not get it to work. Just an FYI, if you are torn, I recommend going with gulp-sass. :D

For the purpose of this tutorial I am assuming a project structure that looks like this...

-index.html
--assets
---styles
----sass
-----index.scss
----css

The 'styles' Task

//gulpfile.js

var gulp = require('gulp');
var sass = require('gulp-sass');

//style paths
var sassFiles = 'assets/styles/sass/**/*.scss',
    cssDest = 'assets/styles/css/';

gulp.task('styles', function(){
    gulp.src(sassFiles)
        .pipe(sass().on('error', sass.logError))
        .pipe(gulp.dest(cssDest));
});

First, make sure that gulp and gulp-sass are included at the top of your gulpfile.js.

I defined some variables for the style paths so they can be reused as needed. For example, when we get to the point of setting up the watcher, we will reuse the sassFiles path.

In our 'styles' task, we use the gulp.src() method to pass the location of our SCSS files. This path is relative to the gulpfile.js.

Next, we use .pipe() to pass anything returned from .src() into the sass() parser function to compile our SCSS to CSS.

The sass() function emits events if there are errors. We can listen to these events using .on('error', sass.logError)). If there is an error parsing the SCSS, it will let us know where the error is so we can easily fix it.

Then, we use use .pipe() again to send the results from the previous function into the gulp.dest() function, which saves the compiled CSS files to the newly defined location.

Finally, I modified the 'default' gulp task from the previous tutorial, to run our 'styles' task.

Setting up the Watcher

The last thing we want to do is make sure that our SCSS files are compiled every time there is a change. To do that we will add a 'watch' task.

gulp.task('watch',function() {
    gulp.watch(sassFiles,['styles']);
});

gulp.watch() takes two arguments, the location we want to watch and an array of the tasks we want to run when changes are detected. So, we pass in our sassFiles variable for the location to watch and an array that contains a reference to our 'styles' task because it compiles our files.

To test the 'watch' task, run...

gulp watch

You should see the following output in the terminal:

[gulp-demo] Using gulpfile ~/WebDevelopment/gulp-demo/gulpfile.js
[gulp-demo] Starting 'watch'...
[gulp-demo] Finished 'watch' after 5.7 ms

Now, edit a file in the watched directory and see what happens. You should see the following output:

[gulp-demo] Starting 'styles'...
[gulp-demo] Finished 'styles' after 6.33 ms

Let's take this a step further and make sure our error handler is working.

Make a purposeful error in your SCSS file, save, and you should see output similar to the following:

[gulp-demo] Starting 'styles'...
[gulp-demo] Finished 'styles' after 2.19 ms
Error in plugin 'sass'
Message:
    assets/styles/sass/index.scss
Error: Invalid CSS after "		color:#eee": expected "}", was ":;"
        on line 3 of stdin
>> 		color:#eee:;
   --------^

Weeee! It works! Congrats!

I hope you learned something from this tutorial. Please share your questions or comments in a comment below! It's the best way to learn and help others learn more about automating tasks with Gulp! Thanks, have fun, and build cool things!

In the next tutorial, we will learn how concatenate and minify Javascript to improve the performance of our production apps.