Peter Keating

Developer from the New Forest in the South of England.

Using CSSCSS with Grunt

This week a useful tool named CSSCSS popped up on my radar. Built by Zach Moazeni, CSSCSS is a Ruby gem that analyzes CSS and outputs selectors with matching rules. Currently at version 1.2.0, Zach's tool is great for highlighting areas of duplication in stylesheets. By removing matched rules the stylesheet will no longer have duplicate rules, which in turn reduces the file size of the stylesheet. This can help in shaving off those crucial kilobytes from your CSS files. A great use case for CSSCSS is when working with unfamiliar stylesheet. CSSCSS can be used to ensure you're not adding additional CSS that has already been defined somewhere else in the stylesheet. CSSCSS has lots of other little features such as the ability to convert and analyze Sass files or LESS files, output analysis in JSON, ignore dictated properties or selectors and change the minimum number of matched rules before a ruleset is considered matched.

To paint a clear picture of what CSSCSS actually does, lets run through an example. Here is some CSS that will be analyzed, obviously the matched rules are easy to see, but imagine a much larger stylesheet.

.rule-a {  
    border: 1px solid #000;
    margin: 0;
    padding: 0;

.rule-b {
    border: 1px solid #000;
    margin: 0;
    padding: 0;

CSSCSS is installed and used via the command line as shown in the screenshot below. The gem command can only be run if you have Ruby installed, and only needs to be run the first time you want to use CSSCSS. The -v argument instructs CSSCSS to output the properties that have been matched. The --no-color option is required for Windows to ensure the output isn't all mangled (this a bug that should be fixed in a future release). As you can see CSSCSS has outputted that .rule-a and .rule-b are sharing rules. This signals that a refactor of the CSS can be done so only one rule exists that contain the matched properties.

Screenshot of CSSCSS in action.

Now you could execute CSSCSS manually while working on CSS, or CSSCSS could be included as part of the automation process. Over the past month I have spent a lot of time getting stuck into Grunt. Grunt is a JavaScript task runner used to configure an automation process that runs on Node.js. Usually Ant is my preferred tool of choice for automation, however using Grunt makes it simple to configure automation tasks for modern web frameworks and libraries. The Grunt configuration is defined in a JavaScript file that is placed inside your project. This JavaScript file contains tasks that are configured to your automation needs, these tasks a primarily loaded via NPM. NPM is a directory of node packages that can easily be installed into a development environment by running a simple command (npm install). To find out more about Grunt and how it can be configured I suggest reading the well written documentation.

As CSSCSS is relatively new there wasn't a Grunt task for it. I saw this as an opportunity to make an open source contribution by creating a Grunt task that would execute CSSCSS. This would hopefully not only be useful to myself and others, but also offer a great chance to learn more about Grunt and Node.js. The Grunt task, named grunt-csscss, is published on NPM. The source code and documentation is available on Github.

So how do you use it? Firstly you need to have Node.js installed on your machine. Next you need to install the Grunt package via NPM and have a Gruntfile.js file that will contain your automation tasks. Once you have all these you can run the command below to install grunt-csscss as a development dependancy.

npm install grunt-csscss --save-dev  

Once the Grunt task has been installed it can be used in a grunt file. Below is an example of a Grunt file that uses grunt-csscss to analyze style.css with CSSCSS in verbose mode. Multiple files can be analyzed individually by specifying files in the src array. There are many more options available to change the arguments that are passed to CSSCSS.

'use strict';

module.exports = function(grunt) {

    csscss: {
      options: {
        verbose: true
      dist: {
        src: ['style.css']


  grunt.registerTask('default', ['csscss']);

There are more examples of using the csscss task in the documentation.

All this is ready to be used right now, and currently the grunt task supports all the arguments available in CSSCSS version 1.2.0. I will be making sure that the Grunt task continues to support all the features that Zach adds to CSSCSS in the future. Feel free to give it a try, and any feedback is appreciated. You can send feedback by emailing me or opening an issue in the Github repository.

One of the primary things I learnt from creating grunt-csscss was how easy things have been made for developers with tools like Grunt, NPM and Travis CI. If your developing using modern tools, frameworks & libraries like Sass, RequireJS or JSHint to name a few, then you should definitely have Grunt & NPM in your arsenal. Grunt is definitely a game changer for automation. I will definitely be using it as my primary automation tool over Ant. Combined with NPM it makes the retrieval and maintaining of dependencies as simple as writing a command in the command line. NPM also makes it quick and easy to get your own creations online and available for other developers to use. Being on the command line can be daunting to some, but with only a few regular commands to learn and excellent documentation it doesn't take long to master. I highly recommend jumping in and giving it a go.

Massive credit to Zach for his work on CSSCSS, great job!

Back to Posts