grunt-css-annotator

This module contains a couple of grunt task useful for optimizing the css for the critical path.

Getting Started

This plugin requires Grunt ~0.4.0

If you haven't used Grunt before, be sure to check out the Getting Started guide, as it explains how to create a Gruntfile as well as install and use Grunt plugins. Once you're familiar with that process, you may install this plugin with this command:

npm install grunt-css-annotator --save-dev

Once the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:

grunt.loadNpmTasks('grunt-css-annotator');

css-annotator

This grunt task reads a group of css files and collects all the selectors used. Then it checks which of these selectors are used in the pages listed. After that it writes all the css in a folder adding a label next to each css rule used. It uses Phantomjs to scan the webpages so it detects any markup added by Javascript (3 seconds after onDomContentLoaded).

This is an example of the options

"css-annotator": {
    dist:{
        src: 'css/**/*.css',
        dest: 'annotated/',
        label: 'used',
        override: false,
        intersection: false,
        urls: [
            'http://www.example.com/page1.html',
            'http://www.example.com/page2.html',
            'http://www.example.com/page3.html',
        ]
    }
}

This is an example of the annotation (there may be more than one label and they can be edited by hand):

a {
    /*labels:used,article*/
    color: red;
}

a.special {
    /*labels:article*/
    color: green;
}

Options

• src: a group of css. You can use the grunt globbing syntax
• dest: a folder where the resulting css are written. If it is not defined the css will be annotated in place.
• label: this label is added to any css rule that is used
• override: (default false) if there is already a label annotated it doesn't change this label, just updates the empty ones
• intersection: (default false) If this option is false I attach the label to all selectors found. If true I attach the label to the selectors used in all the pages.
• urls an array of urls to parse against the selector extracted from the css

A note about resulting css. CSS is parsed and rewritten by reworq. There is some small and mostly positive side effects:

• not valid css can't be parsed and it throws an error
• some csshacks is not considered to be a valid css
• the css is nicely reformatted
• comments that takes places between selectors are removed

css-annotator-filter

This grunt task filters a css removing the rules annotated with the syntax used by the previous task.

"css-annotator-filter": {
    dist:{
        src: 'css/**/*.css',
        dest: 'filtered/',
        with_label: ['used'],
        without_label: ['foo', 'bar'],
    }
}

Options

• src: a group of css. You can use the grunt globbing syntax
• dest: a folder where the resulting css are written
• with_label: any css rules containing all these label will be preserved
• without_label: any css rules containing one of these label will be removed

Status

This package is considered experimental. Use it at your own risk !!!

Credits

Many thanks to the Mailonline who sponsored this project and allowed an open source release. This project uses GRUNT and REWORK