Gulp + Sass Setup Tutorial Published July 05, 2016

Recently, I was trying to find a tutorial that could help my coworker set up their machine for some basic Sass development, but I was surprised that I was unable to find a concise tutorial to do just that. Every tutorial I found included a slew of other plugins being installed simultaneously that may or may not be appropriate for any given project. So to fill that hole, I've written up a short, bare-bones Sass setup guide.

So let's say you're setting up a basic website and you want to use Sass instead of CSS for your stylesheets. Let's assume you already know how to write Sass, but don't know how to easily compile Sass into CSS as you work. There are multiple ways to do this, but we're going to use gulp to automate the compiling process. Setup for this is pretty simple.

1. Install node.js

Your best route for this step is to just go to and click the "Install" button. Their directions should get you through this step. After you've install node.js, ensure node and npm (node's package manager) are installed properly:

$ node -v  # this should return a version number
# Depending on your node install, you may need to run `nodejs -v` instead
$ npm -v  # this should return a version number also

2. Initialize

First navigate to your website's directory. If your website is in the /apps/my-website/ directory, run:

$ cd /sites/my-website

Then initialize npm, and follow its directions to set up a local package.json file.

$ npm init

3. Install gulp

Gulp is a node package that we'll use to automate the process of compiling our Sass into CSS. First, install gulp via npm like so:

$ sudo npm install -g gulp
# npm install ... installs the package for node
# the -g option specifies that the package should be installed globally on your machine so you can reuse it for other projects

Gulp should now be installed. Check with:

$ gulp -v  # this should return version information for gulp

Finally, install gulp locally:

$ npm install gulp --save-dev  # the --save-dev option adds the gulp dependency to the package.json file created earlier.

4. Install gulp plugins

For this setup, we're going to stick to the bare minimum and only install gulp-sass. The gulp-sass plugin will compile the Sass files into CSS. There are tons of other useful plugins, but there are plenty of other sites with good information on that. Now, install gulp-sass:

$ npm install gulp-sass --save-dev  # the --save-dev option adds gulp-sass to package.json as a dependency also.

5. Create your gulpfile

The gulpfile will tell gulp how to operate within your project. Since we only have the gulp-sass plugin, this is fairly short. Create a new file named gulpfile.js with the following content:

// gulpfile.js

// load gulp
var gulp = require('gulp');

// load gulp-sass plugin
var sass = require('gulp-sass');

// define the gulp "task" that will compile your sass
/* We make a few assumptions here.  Change as your project requires:
*  1. Your sass files are in a scss/ directory at the root of your project
*  2. Your sass files using the "Sassy CSS" syntax, and thus end in .scss
*  3. Your CSS stylesheets will live in the stylesheets/ directory at the root of your project
gulp.task('sass', function() {

// define the gulp task that will watch for changes in your sass
gulp.task('watch', function() {'scss/*.scss', ['sass']);

// define the default gulp task
gulp.task('default', ['sass', 'watch']);

6. Run gulp and test

Now you should be able to run gulp and it will automatically compile sass in your scss directory both immediately and anytime you edit a .scss file in it. Run it like so:

$ gulp # this runs the 'default' gulp task as defined in our gulpfile.js file.

That's it.

Your sass is now automatically converted to css while you code. Happy coding. In the terminal where gulp is running, you should see it working every time you change a .scss file, so when you reload your page, the updates sass should automatically update your CSS containing the compiled version of it.

What else?

As I mentioned before, there are tons of other gulp plugins, including ones to automatically refresh your browser when you change local files (see the browser-sync plugin), so feel free to explore plugins and find some neat ones to make your development life easier.