Noteworthy Programming Masterpiece

    This package has been deprecated

    Author message:

    Package no longer supported. Contact Support at https://www.npmjs.com/support for more info.

    exact-critical

    1.0.0 • Public • Published

    critical NPM version Build Status Build status Dependency Status

    Critical extracts & inlines critical-path (above-the-fold) CSS from HTML

    Install

    $ npm install --save critical
    

    Build plugins

    Demo projects

    Usage

    Include:

    var critical = require('critical');

    Generate and inline critical-path CSS

    critical.generateInline({
        // Your base directory
        base: 'dist/',
     
        // HTML source
        html: '<html>...</html>',
     
        // HTML source file
        src: 'index.html',
     
        // Your CSS Files (optional)
        css: ['dist/styles/main.css'],
     
        // Viewport width
        width: 1300,
     
        // Viewport height
        height: 900,
     
        // Target for final HTML output
        htmlTarget: 'index-critical.html',
     
        // Target for generated critical-path CSS (which we inline)
        styleTarget: 'styles/main.css',
     
        // Minify critical-path CSS when inlining
        minify: true,
     
        // Extract inlined styles from referenced stylesheets
        extract: true
    });

    Generate critical-path CSS

    Basic usage:

    critical.generate({
        base: 'test/',
        src: 'index.html',
        dest: 'styles/main.css',
        width: 1300,
        height: 900
    });

    Generate and minify critical-path CSS:

    critical.generate({
        base: 'test/',
        src: 'index.html',
        dest: 'styles/styles.min.css',
        minify: true,
        width: 1300,
        height: 900
    });

    Generate and return output via a callback:

    critical.generate({
        base: 'test/',
        src: 'index.html',
        width: 1300,
        height: 900
    }, function (err, output) {
        // You now have critical-path CSS
        // Works with and without dest specified
    });

    Generate critical-path CSS with multiple resolutions

    When your site is adaptive and you want to deliver critical CSS for multiple screen resolutions this is a useful option. note: (your final output will be minified as to eliminate duplicate rule inclusion)

    critical.generate({
        base: 'test/',
        src: 'index.html',
        dest: 'styles/main.css',
        dimensions: [{
            height: 200,
            width: 500
        }, {
            height: 900,
            width: 1200
        }]
    });

    Inline <style> / critical CSS from generation

    Basic usage:

    critical.inline({
        base: 'test/',
        src: 'index-critical.html',
        dest: 'inlined.html'
    });

    Minify and inline stylesheets:

    critical.inline({
        base: 'test/',
        src: 'index-critical.html',
        dest: 'inlined-minified.html',
        minify: true
    });

    Inline and return output via a callback:

    critical.inline({
        base: 'test/',
        src: 'index-critical.html'
    }, function (err, output){
        // You now have HTML with inlined critical-path CSS
        // Works with and without dest specified
    });

    Options

    Name Type Description
    base string Base directory in which the source and destination are to be written
    html string HTML source to be operated against. This option takes precedence over the src option
    src string Location of the HTML source to be operated against
    dest string Location of where to save the output of an operation
    width integer (Generation only) Width of the target viewport
    height integer (Generation only) Height of the target viewport
    dimensions array (Generation only) an array of objects containing height and width.
    minify boolean Enable minification of CSS output
    extract boolean Remove the inlined styles from any stylesheets referenced in the HTML. It generates new references based on extracted content so it's safe to use for multiple HTML files referencing the same stylesheet
    styleTarget string (generateInline only) Destination for critical-path styles
    htmlTarget string (generateInline only) Destination for (critical-path CSS) style-inlined HTML
    inlineImages boolean Inline images (default: false)
    maxImageFileSize integer Sets a max file size (in bytes) for base64 inlined images
    pathPrefix string (defaults to /) Path to prepend CSS assets with. You must make this path absolute if you are going to be using critical in multiple target files in disparate directory depths. (eg. targeting both /index.html and /admin/index.html would require this path to start with / or it wouldn't work.)

    CLI

    critical works well with standard input.

    $ cat test/fixture/index.html | critical --base test/fixture > critical.css
    

    You can also pass in the critical CSS file as an option.

    $ critical test/fixture/index.html --base test/fixture > critical.css
    

    Why?

    Why is critical-path CSS important?

    CSS is required to construct the render tree for your pages and JavaScript will often block on CSS during initial construction of the page. You should ensure that any non-essential CSS is marked as non-critical (e.g. print and other media queries), and that the amount of critical CSS and the time to deliver it is as small as possible.

    Why should critical-path CSS be inlined?

    For best performance, you may want to consider inlining the critical CSS directly into the HTML document. This eliminates additional roundtrips in the critical path and if done correctly can be used to deliver a “one roundtrip” critical path length where only the HTML is a blocking resource.

    FAQ

    Are there any sample projects available using Critical?

    Why, yes!. Take a look at this Gulp project which demonstrates using Critical to generate and inline critical-path CSS. It also includes a mini-tutorial that walks through how to use it in a simple webapp.

    When should I just use Penthouse directly?

    The main differences between Critical and Penthouse, a module we use, are:

    • Critical will automatically extract stylesheets from your HTML from which to generate critical-path CSS from, whilst other modules generally require you to specify this upfront.
    • Critical provides methods for inlining critical-path CSS (a common logical next-step once your CSS is generated)
    • Since we tackle both generation and inlining, we're able to abstract away some of the ugly boilerplate otherwise involved in tackling these problems separately.

    That said, if your site or app has a large number of styles or styles which are being dynamically injected into the DOM (sometimes common in Angular apps) I recommend using Penthouse directly. It will require you to supply styles upfront, but this may provide a higher level of accuracy if you find Critical isn't serving your needs.

    What other alternatives to Critical are available?

    FilamentGroup maintain a criticalCSS node module, which similar to Penthouse will find and output the critical-path CSS for your pages.

    Is Critical stable and suitable for production use?

    Many of the current tools around critical-path CSS are in an experimental stage and are constantly striving to improve. The same could be said of Critical. It hasn't been extensively tested on a ton of sites and it's very possible something may well break. That said, we welcome you to try it out on your project and report bugs if you find them.

    Can I contribute?

    Of course. We appreciate all of our contributors and welcome contributions to improve the project further. If you're uncertain whether an addition should be made, feel free to open up an issue and we can discuss it.

    License

    Apache-2.0 © Addy Osmani

    Install

    npm i exact-critical

    DownloadsWeekly Downloads

    1

    Version

    1.0.0

    License

    Apache-2.0

    Last publish

    Collaborators

    • cmcculloh