Grunt workflow with Magento rwd theme

Hi! Today I will tell you how to set up your Grunt environment to use with Magento rwd theme.

In the official Responsive Web Developer's Guide it is said that:

the new Magento responsive theme uses the Compass library to compile its Sass files into CSS, you must install Compass in your development environment

To use the Compass within the Grunt we need to install grunt-contrib-compass

In order for this plugin to work we need to check if our system is properly configured:

This task requires you to have Ruby, Sass, and Compass >=1.0.1 installed. If you're on OS X or Linux you probably already have Ruby installed; test with ruby -v in your terminal. When you've confirmed you have Ruby installed, run gem update --system && gem install compass to install Compass and Sass.

Simple environment

Lets start with some simple example where we will use grunt to compile scss files into css. Follow these steps:

1. go to the theme root directory (for example rwd/default)

2. create a file named package.json with following contents:

{
  "name": "grunt for magento rwd",
  "devDependencies": {
    "grunt": "^0.4.5",
    "grunt-contrib-compass": "^1.0.3",
  }
}

3. open Terminal and install the dependencies with npm install

4. create a file named Gruntfile.js with following contents:

module.exports = function(grunt) {
  grunt.initConfig({
    compass: {
      dist: {
        options: {
          sassDir: 'scss',
          cssDir: 'css',
          outputStyle: 'compact',
          watch: {
            options: {}
          },
          force: true
        }
      }
    }
  });

  grunt.loadNpmTasks('grunt-contrib-compass');
  grunt.registerTask('default', ['compass']);
}

5. run grunt in the Terminal to compile the scss files into css

Advanced environment

We can go further and add more plugins to our environment. For example we can install grunt-contrib-uglify to minify our js files and grunt-contrib-watch to automatically compile css and minify js files when some changes are made. Follow these steps:

1. Open Terminal and enter the following npm install grunt-contrib-uglify --save-dev and npm install grunt-contrib-watch --save-dev

Now your package.json should look like this:

{
  "name": "grunt for magento rwd",
  "devDependencies": {
    "grunt": "^0.4.5",
    "grunt-contrib-compass": "^1.0.3",
    "grunt-contrib-uglify": "^0.9.1",
    "grunt-contrib-watch": "^0.6.1"
  }
}

2. In this example we are using grunt-contrib-watch for checking file changes, so we need to change our Compass configuration to compile instead of watch so in Gruntfile.js it should look like this:

compass: {
  dist: {
    options: {
      sassDir: 'scss',
      cssDir: 'css',
      outputStyle: 'compact',
      compile: {
        options: {}
      },
      force: true
    }
  }
}

3. Now we need to configure grunt-contrib-uglify:

uglify: {
  my_target: {
    files: {
      'js/app.js': ['js_src/app.js']
    }
  }
}

4. The final thing we need to configure is grunt-contrib-watch:

watch: {
    compass: {
      files: ['scss/*.scss', 'scss/**/*.scss'],
      tasks: 'compass:dist'
    },
    uglify: {
      files: 'js_src/*.js',
      tasks: 'uglify'
    }
}

Our final Gruntfile.js should look like this:

module.exports = function(grunt) {
  grunt.initConfig({
    compass: {                  // Task
      dist: {                   // Target
        options: {              // Target options
          sassDir: 'scss',
          cssDir: 'css',
          outputStyle: 'compact',
          compile: {
            options: {}
          },
          force: true
        }
      }
    },

    uglify: {
      my_target: {
        files: {
          'js/app.js': ['js_src/app.js']
        }
      }
    },

    watch: {
        compass: {
          files: ['scss/*.scss', 'scss/**/*.scss'],
          tasks: 'compass:dist'
        },
        uglify: {
          files: 'js_src/*.js',
          tasks: 'uglify'
        }
      } 
  });

  grunt.loadNpmTasks('grunt-contrib-compass');
  grunt.loadNpmTasks('grunt-contrib-watch');
  grunt.loadNpmTasks('grunt-contrib-uglify');

  grunt.registerTask('build', ['compass']);
  grunt.registerTask('default', ['watch']);
}

That's it. If you have any questions leave a comment below.