grunt-criticalcss-server
v1.2.1
Published
Build critical css rulesets for non-static mvc based web applications.
Downloads
9
Maintainers
Readme
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)