Setting up Gulp with Magento 1.9

Just last week I was introduced to Gulp by one of my colleagues. After a short presentation about how and why to use Gulp, I was sold. ‘Why haven’t I been using this before?’ was my immediate thought!

If you don’t want to read the background, skip to the good bit here.

I won’t go through all the features and benefits of using Gulp (there are plenty of other blog posts around the internet which I’ll let persuade you). Instead, I want to share one of my Eureka moments with you, which was when I managed to get Gulp and Magento working seamlessly, specifically Magento 1.9.

Gulp & Magento

Here at Creare, we use WordPress and Magento day in, day out, so getting Gulp to work with both these platforms is essential for us to be able to move forwards. Getting Gulp to work with WordPress is very straight forward and nothing out of the ordinary is required. Magento 1.9 on the other hand was slightly more tricky. Now you may also be thinking, why is this specifically aimed at Magento 1.9? The reason is – SASS.

One of the great features of Magento is its fallback system. If a file isn’t found in your theme, Magento will fall back through the themes to try and find the file it’s looking for (this fallback process is a set process which has been built in to Magento). Here’s a brief explanation.

So this all sounds great so far but when we’re talking about compiling SASS, this get’s a little more complex. Essentially, we need to make sure we can compile SASS but retain the fallback system in Magento, so if a particular scss file isn’t present in our configured theme, the fallback is in place to grab the file from our default theme.

You still with me? Good, let’s continue…

So we’ve covered some of the background, now let’s get stuck in and set this up!

At this point, I need to assume that you’ve already done the following (if you haven’t, do so before continuing):

  • Installed Magento
  • Created a new package for your theme
  • Created a new theme folder
  • Your Magento design settings reflect the change (System > Configuration > General > Design)
  • Node.js is installed on your computer & Gulp is installed globally
  • You have some knowledge of Gulp (this is a good starting point if not)

Now we’re going to install Gulp into your project. In command line, browse into /skin/frontend/your_package/your_theme/ and make this your active directory. Once in there, in command line, you’re going to need to type:

npm init

Command line will prompt you with a few questions which you can hit enter to skip or type what you want in each of the sections.

Once completed, a package.json file will be created in your directory. This file contains meta data about your project, one of these things is dependencies.

Now you want to install Gulp locally to your project with the following command:

npm install gulp --save-dev

You’ll know if this has worked correctly by typing ‘gulp -v‘ into command line, this should show you two versions of Gulp; Global and Local.

An example of Global and Local Gulp versions
An example of Global and Local Gulp versions

The next thing you need is a gulpfile.js to be created on the same level as the package.json file (you shouldn’t have changed directories in command line). This is basically the configuration file for Gulp, so it knows what to do with your project. You can leave this empty for now, as we need to create another file first.

On the same level as the package.json and gulpfile.js file, you need to create a config.rb file. This file is a compass configuration file, which is very important for us and the fall back system we want to utilise! Inside that config.rb file, you want to paste the following:

## Path to assets
http_path = "/skin/frontend/your_package/your_theme/"
css_dir = "css"
sass_dir = "scss"
images_dir = "images"
javascripts_dir = "js"

## Fallback path
add_import_path "../../rwd/default/scss"

## Enable relative assets
relative_assets = true

## Output style
output_style = :expanded #:expanded / :nested / :compact / :compressed
environment = :development # :production / :development

## SASS Options
line_comments = true

This is really important, especially the ‘add_import_path’ part. This is what tells Gulp to look for the missing files in your specified fallback destination. I’ve set this to fallback to the RWD package and the default theme (which is default in Magento 1.9).

For Gulp to compile your SCSS files, we need to install a plugin. The plugin I used is gulp-compass. The reason we use gulp-compass and not gulp-sass to compile, is that Magento SCSS requires gulp-compass and will not work with just gulp-sass. So to install gulp-compass, we need to go back to command line (same directory as before) and type the following:

npm install gulp-compass --save-dev

This will install the required Compass plugin into your project, which we can now use. We can now go back to the gulpfile.js now and set up some tasks. I used the following (yours may differ if you have other plugins):

// Load plugins
gulp = require('gulp'),
compass = require('gulp-compass');

var paths = {
scss: ['scss/*.scss', 'scss/*/*.scss']

// Compass task
gulp.task('compass', function() {
config_file: 'config.rb',
css: 'css',
sass: 'scss'

// Default task
gulp.task('default', function() {, ['compass']);

EDIT: You’ll notice in the above configuration that I’ve included a variable of paths and in that, defined all places where my .scss files are which could be edited. If you don’t do this and just ask Gulp to watch one location of .scss files, if you edit scss within a sub-folder then the Watch task won’t run. The Compass task runs fine, Gulp just can’t tell which files have been changed. You can do this with any file type, not just .scss, it could be useful for images & scripts if you’re using certain Gulp plugins.

So that’s all the configuration done, now we can try and put this into practice. Copy over the SCSS folder from /skin/frontend/rwd/default/ into your new package and theme. From your theme, you can delete the following folders from inside the scss folder:

  • Core
  • Function
  • Layout
  • Mixin
  • Module
  • Override
  • Vendor

EDIT: The only thing you actually need to copy over is the style.scss file to ensure this is working. We’ve set up the fallback in our config.rb file so any file which is not in your theme, gulp will grab from your desired fallback destination.

Now you only need to copy over the files you need to change instead of having all the files in your theme, despite whether you change them or not.

The only thing left to do is to browse into the scss directory in command line and then run the command ‘gulp‘. We set up a default task in our gulpfile.js so we don’t need to specify an exact task to run.

EDIT: If you’re having problems with Gulp not running at this point, it might be that you also need Compass installed on your computer. You can get it from here –

When you modify some SASS in your new theme, you’ll see that Gulp compiles the files from your configured theme and the fallback (defined in config.rb).

So that’s it, you’re all set up and ready to go! Remember, you can find a lot of useful plugins on the Gulp website to speed up your development.

Not mentioning any names, but the previous method I was using to compile SASS with Magento took about 10-15 seconds…Gulp takes 5 seconds, maximum!! When combined with gulp-livereload and the Chrome LiveReload Extension, development is a much quicker process.

I hope you can find this useful and if you have set your project up differently, comment below!

  • Paweł Grzybek

    Wow! Thats super cool article my friend! Very helpful tip. Hopefully Magneto core on new version will leave compass dependency. Do not forgot about error handling on your task. My only advice is to use browserSync instead of LiveReload. It comes with so many cool additional features.

    • daniel_c_long

      Thanks Pawel, will take a look at browserSync instead – not really used either so will check it out. And thanks for introducing me to Gulp!

      • Paweł Grzybek

        You are welcome man! Glad you like gulp!

  • Stef Kay

    Hey, great article, i’d suggest pulling in the minify package aswell and piping that to the task.

    • daniel_c_long

      Thanks for the comment Stef. Thanks for your suggestion, I’ll take a look at that package and add into the task!

  • Ljubisa Djordjevic

    You said magento require gulp-compass, why not gulp sass? Do you had some speed improvements on compiling time with this setup over just compass?

    • daniel_c_long

      Hi Ljubisa, thanks for your comment and it’s a very good question actually, which I might not have explained very well.

      The answer is simply the following; Magento 1.9 uses the Compass SASS library to add mainly mixins to the stylesheet. Without using Compass, the compiling process will fail, as the Compass mixins will not be found in just your general SASS compiler. So you have two options, either:

      1. Use a Compass compiler

      2. Strip out all of the Compass required mixins and use a SASS compiler.

      Personally, I’d recommend the first option. Hope this helps!

      You can also check out this link here for a bit more info –

      • Ljubisa Djordjevic

        Tnx Daniel for answer and article. I just tried your setup and yes is faster then default compass that came with magento. That’s super, but I’m thinking to use gulp-sass,(libsass) and take advantage of great speed :). Compass mixins can be substituted with bourbon, mostly same names for mixins. Maybe few of them need to be striped out.

        • daniel_c_long

          No problem. If you do find it is much quicker, it’d be great if you could leave a message so I can give it a go myself :)

  • Tadeo Barranco

    Hi Daniel i just implement that and yes gulp compiled my scss file, i just use the styles.scss and it create me a styles.css but when I go to my Magento implementation frontend it seems broken.

    • daniel_c_long

      Hi Tadeo,
      When you say the frontend is broken, what do you mean? Have you got a link I can look at? Using Gulp shouldn’t break your website as it deals with the JS & CSS. Let me know more detail if you can and we can try and debug.

  • Michael van Eijden

    How to correctly set this up for a multistore with multiple themes in one theme package?