Getting started with Gulp and Sass

April 13th, 2015

gulp_sass

A few years ago I wrote an article on Getting started with Grunt and Sass. I wanted to write one about using Gulp and gulp-sass since gulp is starting to become more widely used.

Lets get started! First things first, cd into the the project that you want add gulp. If you are not familiar with the command line check out my article Getting comfortable on the Command Line. Whenever starting a new gulp file from scratch we start by running npm init. This will start creating a package.json file. Enter the data as you need, or just hit enter and it will add what is in the () into the package.json file. Once that is done we are ready to get started.

Installing gulp

If you have not installed gulp before, have to make sure you install it globally first. Start by running npm install -g gulp, once that has completed we need to add it to our project, type npm install --save-dev gulp. This will install gulp and the --save-dev will add gulp as a devDependency in your package.json file. We also need to do the same for gulp-sass, in total these are the commands we need to run:


npm init //This will run through creating the package.json file
npm install -g gulp //If you haven't installed gulp globally before
npm install --save-dev gulp
npm install --save-dev gulp-sass

Once that is done we are ready to start writing some JS!

Project setup

In order for this to make sense lets assume you have a specific folder structure.


- index.html
--sass
   - style.scss
-- css
package.json
Gulpfile.js

In our root folder we have a sass and a css folder. Inside the sass folder we have our style.scss that we want to compile into css.

Setting up the Gulp file.

Alright! Lets get into actually writing the JS. Inside the Gulpfile.js we need to do a few things. First we need to get access to gulp, and then we have to actually set up the task that will run and compile the sass to css.


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

Since gulp runs on node, we use the require() function to get access to our modules.

Now let’s build the actual task.


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

gulp.task('styles', function() {
    gulp.src('sass/**/*.scss')
        .pipe(sass().on('error', sass.logError))
        .pipe(gulp.dest('./css/'));
});

Let’s break this down a bit. First we add gulp.task() this is how we define our tasks in gulp. This method takes two arguments, the name of the task, and a callback function to run the actual task. In this case we call it ‘styles’. Next we set up what files we want to look at, to do that we use gulp.src() inside there we pass a string of the location of the files we want to watch, this path is relative to the gulpfile.js.

Next we use the .pipe() method to pass along anything from the .src() inside of this method we use the imported sass module to compile our sass. The sass function emits events if there is an error, so we can listen to this event using .on('error', sass.logError)). This one is important, because if there is an error parsing your sass by default it will just kill the gulp process, but with this option it will tell us where the error is!

The final step is to tell gulp where to put the newly compiled sass. To do this we use the .pipe() method to take the data from the previous .pipe(). To set the destination we use the .dest() method. In this method we add a string that will be the path to the destination we want to output our new css too. Much like the .src() path, this is relative to our gulpfile.js. In this case we set it to be output into our css folder. And that will be that, this task takes our style.scss compiles it and outputs it as a style.css file in our css folder!

Running the gulpfile

In order to run our gulp we simply go to the terminal and type gulp styles where ‘styles’ is the name of that task we created! However, this can get a bit repetitive if we are working! Lets set up a simple task to watch our files.


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

gulp.task('styles', function() {
    gulp.src('sass/**/*.scss')
        .pipe(sass().on('error', sass.logError))
        .pipe(gulp.dest('./css/'))
});

//Watch task
gulp.task('default',function() {
    gulp.watch('sass/**/*.scss',['styles']);
});

This last task is very simple, we use the .watch() method. We pass in the path to the files we want to watch, and then pass in an array with the tasks that we want to run when the files are changed. The great thing about this task is since we have called this task ‘default’, we can just run gulp when we want to run gulp, no need to specify a task! And it will now just sit and wait for files to be saved and then run our task!

And that is it, I hope that is helpful to you, if you have any questions let pop them in the comments!

  • tomstill

    There’s a little error on this line: gulp.src(‘sass/**/*/scss’) – should be .scss?

    • rchristiani

      Correct! Thanks!

  • javier aliaga

    when the SCSS errors is to gulp as do I prevent this?

    • Ryan Christiani

      Not sure what you mean. With the errLogToConsole: true option you should see the error and the line it is on. Does that help?

  • tikitariki

    Hey man, thanks for writing this. Where did you find “errLogToConsole” for gulp-sass? The documentation for npm modules are always so sparse. I’m just wondering because in the gulp-sass package’s docs (https://www.npmjs.com/package/gulp-sass) have a different way of outputting errors.

    • tikitariki

      errLogToConsole is deprecated. The rest of your code is unaffected by this. http://stackoverflow.com/a/30742014/385811

      • Ryan Christiani

        Oh wow, yeah, they seem to have taken that out and changed it to be .pipe(sass().on(‘error’, sass.logError)). Thanks I will update the post.

  • Kamal Sharif

    Very helpful. Thank you 🙂

  • Felipe Pastor

    How can i use Compass mixins with gulp-sass? Is there any option?
    Thanks.

  • Paweł Poździej

    This is great! Thank you very much.

  • http://shivsoftwares.blogspot.in Abhishek

    Silly question …
    I am new to npm/glup/saas
    Why used double star ** in file searching pattern

    sass/**/*.scss

    but our style.scss file is located in sass/style.scss

    • Ryan Christiani

      Hey!

      We use the `sass/**/*.scss` pattern so that we can add folders to your sass folder, and our gulp file will still see them!

  • Luke Diebold

    Thanks for this!

    I love a short, simple tutorial that explains all of the code!

    • Anthony

      Amen to that. I cant stand when people use the most complicated scenarios for a simple subject.

  • Jiro Lin

    I really like this tutorial, very clear and the demo are easy to understand~

    https://github.com/jiro9611

  • http://ykbks.com/ Yousuf Kamal

    This is excellent writing! Thank you!

  • devil

    thanks

  • Pingback: Node.js, Gulp & npm | Pearltrees()

  • vsenetak

    Please, help me!
    The plugin don’t understent f.e.:
    @media screen and (max-width: 640px){
    p{color: red;}
    }
    as result have an error: invalid css after width: 640px){ expected “}”

    • Ryan Christiani

      I suspect the error is on a line above, not this line. Check your syntax!

  • Soumen Naskar

    Its indeed a nice tutorial. I have followed this, unfortunately getting an error. error text:

    Error: error reading values after
    on line 35 of sass/sass1/nr-layouts/_parents-home.scss
    >> height: 50% !Important;

    Here is the class definition:

    .photo-layover {
    height: 50% !Important;
    background: rgba(81, 87, 86, 0.69) !Important;
    }

    Can you help me out!

    Thanks in advance.

    • cornelism

      try:
      height: 50%!important;

  • Oleg Zhermal

    I would put gulp.watch(‘sass/**/*.scss’,[‘styles’]); in ‘styles’ task itself… why bother running gulp once again =))

  • Beto Galvez

    I’ve been trying to find a tutorial for a couple of weeks; to explain a very simple solution on how to work with Gulp and Sass. I had an “eureka!” moment when I witness my first task go threw with-out any errors (a noob smile). It’s amazing how it actually shows how to fix CSS errors! Thank you!

  • Pingback: Converting WordPress to Web App: Adding a Build Process | Aaron T. Grogg()

  • Zac Dobbs

    I could really use help understanding how to set up a live reload as well. This made the process very simple to understand as I’m still fairly new to JS.

    • Ryan Christiani

      Check out the Browsersync + gulp example. https://www.browsersync.io/docs/gulp/

      It is pretty straight forward, the section on sass + css injecting.

      It would look something like this.

      var gulp = require(‘gulp’);
      var browserSync = require(‘browser-sync’);
      var reload = browserSync.reload;
      var sass = require(‘gulp-sass’);

      gulp.task(‘styles’, function() {
      gulp.src(‘app/styles/app.scss’)
      .pipe(sass())
      .pipe(gulp.dest(‘app/styles/’))
      .pipe(reload({stream:true}));
      });

      gulp.task(‘browser’, function () {
      browserSync({
      server: {
      baseDir: ‘./’
      }
      });
      });

      gulp.task(‘default’, [‘styles’,’browser’], function() {
      gulp.watch(‘app/styles/**/*.scss’, [‘styles’]);
      });

      Hope that helps.

  • Nurlan Mirzayev

    And what about compass???? Is it same way for compass???

  • Henning Fischer

    Stupid question: I don’t need compass for this to be running? Sorry I am very new to these things. But with this article I got my first project running without bootstrap :).

    • Ryan Christiani

      You do not need compass no! This is just sass.

  • theKevin

    short but useful .thanks

  • S_Y

    For future reference, until I added a return in the ‘styles’ function, the task would compile but never finish. This didn’t come up until I actually started using the watch function and was wondering why it only ever seemed to run once. Otherwise, everything else seems fine and was perfectly helpful.

  • keval
  • Kalin Chernev

    Neat, works like a charm, thanks! 🙂

  • Mik

    I created the template repository to quick start with gulp scss. Lets check it:
    https://github.com/aziev/simplate

  • Norm Brown

    For Gulp 4, need to give anonymous function a name, like “function(done)”.
    Then insert as last line, “done();” which signals async completion required by Gulp 4.

  • Agus Cardeilhac

    Ryan. How are you ?. Really awesome article !. Love it ! 😀

  • Ersin Sayım

    Hi Ryan,

    Thank for this great article. It’s so helpfull.

  • http://picrasma-excelsa.blogspot.com/ Florence Okosun

    thanks

  • Szabo Gergo

    I am still try to figure out why is it better to compiple SASS with Gulp or Grunt than just simply use the sass –watch command?

    • Ryan Christiani

      I mean it is totally up to you, you can use just the sass command, or if you have many other tasks that you want to run a task runner like Gulp, or Grunt seems to make more sense.

      For example, say you are wanting to compile your sass, lint your JS and minifiy it as you go. Instead of having a separate process running for each, why not have a task runner take care of it for you.

      Lots of options out there!

  • Ryan Rahman Setiawan

    Thanks, really help me 🙂

  • Roberto Vargas Castro

    Thanks, works fine

  • Robin

    After setting up NPM and gulp & navigating to the project directory I used the terminal command – touch gulpfile.js – expecting a blank file which I’d need to write but No! All of the work was done for me – all code written here and more to take care of compiling. Thanks for your detailed tutorial, got me set up with ease & helps me better understand what going on in my new file.

    One small piece of feedback – I was following through your instructions & was thrown a little when I found I had to ‘NPM innit’ after installing everything else. I’d have found it useful to have “in total these are the commands we need to run:” or similar at the top and not the first paragraph down.

  • Maq Said

    Very Well Explained.