Home

Awesome

NPM version Build Status Coverage

critical

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

<img src="https://raw.githubusercontent.com/addyosmani/critical/master/preview.png" alt="Preview" width="378">

Install

npm i -D critical

Build plugins

Demo projects

Usage

Include:

import {generate} from 'critical';

Full blown example with available options:

generate({
  // Inline the generated critical-path CSS
  // - true generates HTML
  // - false generates CSS
  inline: true,

  // 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,

  // Output results to file
  target: {
    css: 'critical.css',
    html: 'index-critical.html',
    uncritical: 'uncritical.css',
  },

  // Extract inlined styles from referenced stylesheets
  extract: true,

  // ignore CSS rules
  ignore: {
    atrule: ['@font-face'],
    rule: [/some-regexp/],
    decl: (node, value) => /big-image\.png/.test(value),
  },
});

Generate and inline critical-path CSS

Basic usage:

generate({
  inline: true,
  base: 'test/',
  src: 'index.html',
  target: 'index-critical.html',
  width: 1300,
  height: 900,
});

Generate critical-path CSS

Basic usage:

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

Generate and minify critical-path CSS:

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

Generate, minify and inline critical-path CSS:

generate({
  inline: true,
  base: 'test/',
  src: 'index.html',
  target: {
    html: 'index-critical.html',
    css: 'critical.css',
  },
  width: 1300,
  height: 900,
});

Generate and return output via callback:

generate({
    base: 'test/',
    src: 'index.html',
    width: 1300,
    height: 900,
    inline: true
}, (err, {css, html, uncritical}) => {
    // You now have critical-path CSS as well as the modified HTML.
    // Works with and without target specified.
    ...
});

Generate and return output via promise:

generate({
    base: 'test/',
    src: 'index.html',
    width: 1300,
    height: 900
}).then((({css, html, uncritical})) => {
    // You now have critical-path CSS as well as the modified HTML.
    // Works with and without target specified.
    ...
}).error(err => {
    ...
});

Generate and return output via async function:

const {css, html, uncritical} = await generate({
  base: 'test/',
  src: 'index.html',
  width: 1300,
  height: 900,
});

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)

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

Generate critical-path CSS and ignore specific selectors

This is a useful option when you e.g. want to defer loading of webfonts or background images.

generate({
  base: 'test/',
  src: 'index.html',
  target: {
    css: 'styles/main.css',
  },
  ignore: {
    atrule: ['@font-face'],
    decl: (node, value) => /url\(/.test(value),
  },
});

Generate critical-path CSS and specify asset rebase behaviour

generate({
  base: 'test/',
  src: 'index.html',
  target: {
    css: 'styles/main.css',
  },
  rebase: {
    from: '/styles/main.css',
    to: '/folder/subfolder/index.html',
  },
});
generate({
  base: 'test/',
  src: 'index.html',
  target: {
    css: 'styles/main.css',
  },
  rebase: (asset) => `https://my-cdn.com${asset.absolutePath}`,
});

Options

NameTypeDefaultDescription
inlineboolean|objectfalseInline critical-path CSS using filamentgroup's loadCSS. Pass an object to configure inline-critical
basestringpath.dirname(src) or process.cwd()Base directory in which the source and destination are to be written
htmlstringHTML source to be operated against. This option takes precedence over the src option.
cssarray[]An array of paths to css files, file globs, Vinyl file objects or source CSS strings.
srcstringLocation of the HTML source to be operated against
targetstring or objectLocation of where to save the output of an operation. Use an object with 'html' and 'css' props if you want to store both
widthinteger1300Width of the target viewport
heightinteger900Height of the target viewport
dimensionsarray[]An array of objects containing height and width. Takes precedence over width and height if set
extractbooleanfalseRemove 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. Use with caution. Removing the critical CSS per page results in a unique async loaded CSS file for every page. Meaning you can't rely on cache across multiple pages
inlineImagesbooleanfalseInline images
assetPathsarray[]List of directories/urls where the inliner should start looking for assets
maxImageFileSizeinteger10240Sets a max file size (in bytes) for base64 inlined images
rebaseobject or functionundefinedCritical tries it's best to rebase the asset paths relative to the document. If this doesn't work as expected you can always use this option to control the rebase paths. See postcss-url for details. (https://github.com/pocketjoso/penthouse#usage-1).
ignorearray or objectundefinedIgnore CSS rules. See postcss-discard for usage examples. If you pass an array all rules will be applied to atrules, rules and declarations;
ignoreInlinedStylesbooleanfalseIgnore inlined stylesheets
userAgentstring''User agent to use when fetching a remote src
penthouseobject{}Configuration options for penthouse.
requestobject{}Configuration options for got.
cleanCSSobject{level: { 1: { all: true }, 2: { all: false, removeDuplicateFontRules: true, removeDuplicateMediaBlocks: true, removeDuplicateRules: true, removeEmpty: true, mergeMedia: true } }}Configuration options for CleanCSS which let's you configure the optimization level for the generated critical css
userstringundefinedRFC2617 basic authorization: user
passstringundefinedRFC2617 basic authorization: pass
strictbooleanfalseThrow an error on css parsing errors or if no css is found.

CLI

npm install -g critical

critical works well with standard input.

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

Or on Windows:

type test\fixture\index.html | critical --base test/fixture --inline > index.critical.html

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

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

Gulp

import gulp from 'gulp';
import log from 'fancy-log';
import {stream as critical} from 'critical';

// Generate & Inline Critical-path CSS
gulp.task('critical', () => {
  return gulp
    .src('dist/*.html')
    .pipe(
      critical({
        base: 'dist/',
        inline: true,
        css: ['dist/styles/components.css', 'dist/styles/main.css'],
      })
    )
    .on('error', (err) => {
      log.error(err.message);
    })
    .pipe(gulp.dest('dist'));
});

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:

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. The PageSpeed Optimization modules for nginx, apache, IIS, ATS, and Open Lightspeed can do all the heavy lifting automatically when you enable the prioritize_critical_css filter

Is Critical stable and suitable for production use?

Critical has been used on a number of production sites that have found it stable for everyday use. 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.

Maintainers

This module is brought to you and maintained by the following people:

License

Apache-2.0 © Addy Osmani, Ben Zörb