Critical

Extract & Inline Critical-path CSS in HTML pages

Performance

addyosmani/critical critical

README

[![NPM version][npm-image]][npm-url] [![Build Status][ci-image]][ci-url] [![Coverage][coveralls-image]][coveralls-url]

critical

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

Install

```sh
npm i -D critical
```

Build plugins

- grunt-critical

- Gulp users should use Critical directly

- For Webpack use html-critical-webpack-plugin

Demo projects

- Optimize a basic page with Gulp with a tutorial

- Optimize an Angular boilerplate with Gulp

- Optimize a Weather app with Gulp

Usage

Include:

``` js
import {generate} from 'critical';
```

Full blown example with available options:

``` js
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:

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

Generate critical-path CSS

Basic usage:

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

Generate and minify critical-path CSS:

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

Generate, minify and inline critical-path CSS:

``` js
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:

``` js
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:

``` js
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:

``` js
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)

``` js
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.

``` js
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

``` js
generate({
base: 'test/',
src: 'index.html',
target: {
css: 'styles/main.css',
},
rebase: {
from: '/styles/main.css',
to: '/folder/subfolder/index.html',
},
});
```

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

Options

Name	Type	Default	Description
----------------	----------------------	--------------------------------------	-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
inline	`boolean`\\|`object`	`false`	Inline
base	`string`	`path.dirname(src)`	Base
html	`string`	\|
css	`array`	`[]`	An
src	`string`	\|
target	`string`	\|
width	`integer`	`1300`	Width
height	`integer`	`900`	Height
dimensions	`array`	`[]`	An
extract	`boolean`	`false`	Remove
inlineImages	`boolean`	`false`	Inline
assetPaths	`array`	`[]`	List
maxImageFileSize	`integer`	`10240`	Sets
rebase	`object`	`undefined`	Critical
ignore	`array`	`object`	`undefined`
userAgent	`string`	`''`	User
penthouse	`object`	`{}`	Configuration
request	`object`	`{}`	Configuration
user	`string`	`undefined`	RFC2617
pass	`string`	`undefined`	RFC2617
strict	`boolean`	`false`	Throw

CLI

```sh
npm install -g critical
```

critical works well with standard input.

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

Or on Windows:

```bat
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.

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

Gulp

``` js
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:

- 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. 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:

- Addy Osmani - Creator (Github / Twitter)

- Ben Zörb - Primary maintainer (Github / Twitter)

License

[npm-url]: https://www.npmjs.com/package/critical

[npm-image]: https://img.shields.io/npm/v/critical.svg

[ci-url]: https://github.com/addyosmani/critical/actions?workflow=Tests

[ci-image]: https://github.com/addyosmani/critical/workflows/Tests/badge.svg

[coveralls-url]: https://coveralls.io/github/addyosmani/critical?branch=master

[coveralls-image]: https://img.shields.io/coveralls/github/addyosmani/critical/master.svg