Compiling Sass in a WordPress theme using Grunt

I am developing a WordPress theme using the Underscores theme as my starter theme and I want to automatize the Sass compiling. For this purpose, I will go to use Grunt, a JavaScript Task Runner.

In this example, I will use a Laravel Homestead, a Vagrant Virtual Machine, as my development environment.

Install npm, Grunt, Ruby and Sass

I need this tools:

• npm, a Javascript package manager that allows installing Grunt, Grunt-contrib-sass (the Sass compiler) and Grunt-contrib-watch (a tool that allows running tasks whenever watched files change).
• Ruby and Sass, because the Grunt-contrib-sass requires that I have Ruby and Sass installed.

The virtual machine I am using has npm installed. If you haven’t it installed, you can follow this steps to install it.

You can check if you have npm installed executing:

$ npm -v

You need to have Ruby and Sass installed and in your PATH. You can install it with this commands:

$ sudo apt-get update
$ sudo apt-get install ruby sass

You can check if you have this packages with the commands:

$ ruby -v

and

$ sass -v

Creating the package.json file

Then I have to create the package.json file. The package.json file will be read by npm to download and install the dependencies.

I create the package.json file in the root of the project, then I copy the next content and paste it in the file. This file has 3 dependencies (devDependencies) that will be downloaded and installed in the “node_modules” folder.

{
  "name": "barracoma-wordpress-theme",
  "version": "1.0.0",
  "description": "Barracoma.com wordpress theme",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "author": "Jesús Amieiro",
  "license": "GPL",
  "devDependencies": {
    "grunt": "^1.0.1",
    "grunt-contrib-sass": "^1.0.0",
    "grunt-contrib-watch": "^1.0.0"
  }
}

To install the dependencies I execute from the project root folder:

$ npm install

Now I have a new directory, “node_modules”, with all the packages that I need.

Creating the Gruntfile.js file

Now I have to create the file that will be read by Grunt to execute the tasks.

I Create the Gruntfile.js file in the root of the project and then I copy this content and paste it in the file.

// Use "grunt --help" to list the available tasks

module.exports = function(grunt) {
    grunt.initConfig({
        sass: {
            // this is the "dev" Sass config used with "grunt watch" command
            dev: {
                options: {
                    style: 'expanded',
                },
                files: {
                    // the first path is the output and the second is the input
                    'style.css': 'sass/style.scss'
                }
            },
            // this is the "production" Sass config used with the "grunt default" command
            dist: {
                options: {
                    style: 'compressed',
                },
                files: {
                    'style.css': 'sass/style.scss'
                }
            }
        },
        // configure the "grunt watch" task
        watch: {
            sass: {
                files: ['sass/*.scss', 'sass/**/*.scss',],
                tasks: ['sass:dev']
            }
        }
    });
    grunt.loadNpmTasks('grunt-contrib-sass');
    grunt.loadNpmTasks('grunt-contrib-watch');
    // "grunt" is the same as running "grunt sass:dist".
    grunt.registerTask('default', ['sass:dist']);
    grunt.registerTask('dev', ['sass:dev']);
};

This file has 3 tasks:

• The development compiling, without minifying the CSS file.
• The production or distribution compiling, with the CSS file minified.
• The watch task to run tasks whenever a watched files changes. In this case, I will run the development compiling when a file is changed.

To execute this tasks I have to execute it from the project root folder:

To get help about the grunt command I execute:

$ grunt --help

To compile in the development mode, I execute:

$ grunt sass:dev

The output is a new style.css.

To compile in the production or distribution mode (the default task), I execute:

$ grunt

or

$ grunt sass:dist

The output is a new minified style.css.

To put the shell in watching mode, waiting for a change in some of the files in the “sass” folder, I execute:

$ grunt watch

When I made a change in some of the files in the “sass” folder and save it, the development compiling is executed automatically, getting a new style.css file.