grunt-criticalcss-server

Build page level critical css for ability to render inline for complex multipage apps.

Getting Started

This plugin requires Grunt ~0.4.5

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-criticalcss-server --save-dev

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

grunt.loadNpmTasks('grunt-criticalcss-server');

The "criticalcss" task

grunt criticalcss

This repository was built to support inlining critical css for non-static web applications. Most existing critical/inline css libraries are built for static html and pre-defined css rules. The purpose of this grunt task is to automate inlining critical css files for non-static MVC based applications that require a running web-application server.

In our usage case, our web application pulls data from multiple databases to populate webpages needed for PhantomJS to run criticalCSS.

This grunt task was built based on the awesome support from FilamentGroup's CriticalCSS.

<?php
$stylesheets = array(
  'controller' => array(
    'method_one' => array('controller/method_one.css', 'partial/controller/footer.css'),
    'method_two' => array('controller/method_two.css', 'partial/controller/header.css')
  ),

CSS config

In this example, the web-application contains a css array with a relationship from controller to method. The grunt task requires this mapping to be able to concatenate all method files. When these files are concatenated, the grunt task will use the newly created file to create the css rulset for criticalCSS.

Overview

In your project's Gruntfile, add a section named criticalcss to the data object passed into grunt.initConfig().

grunt.initConfig({
  criticalcss: {
    default : {
      options : {
        app : {
          uri : 'https://localhost/',
        },
        command : {
          cmd : 'php',
          args : ['-r', 'include("path/to/css/mapping.php"); print json_encode($stylesheets);']
        },
        criticalcss : {
          width : 1200,
          height : 900,
          forceInclude : [],
          buffer : 800 * 1024,
          ignoreConsole : true
        },
        css : {
          cache : {
            'menu.css' : 'index.php'
          },
          path : 'css/public/'
        },
        routes : {
          state : {
            default : {
              controller : {
                method_one : 'path/to/method_one',
                method_two : 'path/to/method_two',
              }
            }
          }
        },
        tmpDir : './tmp/'
      }
    }
  },
});

After the CSS config has been loaded via the command option, the routes.state object should be a one-to-one mapping of the controller/method relationship the CSS config file contains. New concatenated css rulesets will be written to the tmpDir. Files within the tmpDir are then loaded into PhantomJS in order to create critical css rulesets.

The newly created css rulesets are written to new files in the same directory as the existing css files defined in the css config (controller/method.critical.css). Those files can then be used to echo content to the controller/method view.

Options

options.app

Type : Object

options.app.uri

Type: String

A string value that is used to designate the application uri.

options.command

Type : Object

options.command.cmd

Type: String

CLI level command to acquire css mapping (controller/method to uri) from running application.

options.criticalcss

Type : Object

These are various options that control the criticalcss environment within PhantomJS.

options.criticalcss.width

Type: Integer Default Value: 1200

The width of the window being used for determining "above the fold"

options.criticalcss.height

Type: Integer Default Value: 900

The height of the window being used for determining "above the fold"

options.criticalcss.forceInclude

Type: Array Default Value: []

An array of selectors that should be included in the critical css no matter what. This is sometimes necessary with js-enhanced components.

options.criticalcss.buffer

Type: Integer Default Value: 800 * 1024

Sets the maxBuffer for child_process.execFile in Node. Necessary for potential memory issues.

options.criticalcss.ignoreConsole

Type: Boolean Default Value: false

Since criticalCSS handles output from STDOUT, it will also catch any outputs to console that are in the JavaScript on a page. If set to true, those will be silenced.

options.css

Type : Object

options.css.cache

Type : Object Optional

A key/value mapping of commonly cached css files that might be globally used and declared in the application css mapping. The key should be equivalent to the css asset and the value should be equivalent to the app route relative to options.app.uri.

options.css.path

Type : String A base directory path that is home to all client facing css assets.

options.routes

Type : Object

options.routes.state

Type : Object

This object should house multiple application states, e.g. default, logged-in, logged-out, cookie-less, etc. Values of this object should contain convential mvc-based routes to the application.

options.tmpDir

Type : String Optional

Contributing

In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code using Grunt.

Release History

(Nothing yet)