Critical extracts & inlines critical-path (above-the-fold) CSS from HTML
$ npm i -D critical@next
$ npm i -D critical@latest
The docs for the latest version can be found here.
We’ve introduced some breaking changes in this release so be sure to check out the changelog.
Include:
var critical = require('critical');
Full blown example with available options:
critical.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'},
// Minify critical-path CSS when inlining
minify: true,
// Extract inlined styles from referenced stylesheets
extract: true,
// Complete Timeout for Operation
timeout: 30000,
// ignore CSS rules
ignore: {
atrule: ['@font-face'],
rule: [/some-regexp/],
decl: (node, value) => /big-image\.png/.test(value)
}
});
Basic usage:
critical.generate({
inline: true,
base: 'test/',
src: 'index.html',
target: 'index-critical.html',
width: 1300,
height: 900
});
Basic usage:
critical.generate({
base: 'test/',
src: 'index.html',
target: 'styles/main.css',
width: 1300,
height: 900
});
Generate and minify critical-path CSS:
critical.generate({
base: 'test/',
src: 'index.html',
target: 'styles/styles.min.css',
width: 1300,
height: 900
});
Generate, minify and inline critical-path CSS:
critical.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:
critical.generate({
base: 'test/',
src: 'index.html',
width: 1300,
height: 900,
inline: true
}, function (err, ({css, html})) {
// You now have critical-path CSS as well as the modified html
// Works with and without target specified
...
});
Generate and return output via promise:
critical.generate({
base: 'test/',
src: 'index.html',
width: 1300,
height: 900
}).then(function (({css, html})) {
// You now have critical-path CSS as well as the modified html
// Works with and without dest specified
...
}).error(function (err) {
...
});
Generate and return output via async function:
const {css} = await critical.generate({
base: 'test/',
src: 'index.html',
width: 1300,
height: 900
});
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
}]
});
This is a useful option when you e.g. want to defer loading of webfonts or background images.
critical.generate({
base: 'test/',
src: 'index.html',
dest: 'styles/main.css',
ignore: {
atrule: ['@font-face'],
decl: (node, value) => /url\(/.test(value)
}
});
critical.generate({
base: 'test/',
src: 'index.html',
dest: 'styles/main.css',
rebase: {from: '/styles/main.css', to: '/folder/subfolder/index.html'}
});
critical.generate({
base: 'test/',
src: 'index.html',
dest: 'styles/main.css',
rebase: asset => `https://my-cdn.com${asset.absolutePath}`
});
| Name | Type | Default | Description |
|---|---|---|---|
| inline | boolean|object | false | Inline critical-path CSS using filamentgroup's loadCSS. Pass an object to configure inline-critical |
| base | string | path.dirname(src) or process.cwd() | 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. | |
| css | array | [] | An array of paths to css files, file globs or Vinyl file objects. |
| src | string | Location of the HTML source to be operated against | |
| target | string | object | |
| width | integer | 1300 | Width of the target viewport |
| height | integer | 900 | Height of the target viewport |
| dimensions | array | [] | An array of objects containing height and width. Takes precedence over width and height if set |
| minify | boolean | true | Enable minification of generated critical-path CSS |
| extract | boolean | false | 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. 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 |
| inlineImages | boolean | false | Inline images |
| assetPaths | array | [] | List of directories/urls where the inliner should start looking for assets |
| maxImageFileSize | integer | 10240 | Sets a max file size (in bytes) for base64 inlined images |
| rebase | object | function | undefined |
| ignore | array | object | undefined |
| userAgent | string | '' | User agent to use when fetching a remote src |
| penthouse | object | {} | Configuration options for penthouse. |
| user | string | undefined | RFC2617 basic authorization: user |
| pass | string | undefined | RFC2617 basic authorization: pass |
$ npm install -g critical
critical works well with standard input.
$ cat 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
var gulp = require('gulp');
var log = require('fancy-log');
var critical = require('critical').stream;
// Generate & Inline Critical-path CSS
gulp.task('critical', function () {
return gulp.src('dist/*.html')
.pipe(critical({base: 'dist/', inline: true, css: ['dist/styles/components.css','dist/styles/main.css']}))
.on('error', function(err) { log.error(err.message); })
.pipe(gulp.dest('dist'));
});
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.
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.
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.
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.
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
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.
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.
This module is brought to you and maintained by the following people:
Apache-2.0 © Addy Osmani, Ben Zörb
FAQs
Extract & Inline Critical-path CSS from HTML
The npm package critical receives a total of 25,462 weekly downloads. As such, critical popularity was classified as popular.
We found that critical demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 0 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
A malicious npm package disguised as a WhatsApp client is exploiting authentication flows with a remote kill switch to exfiltrate data and destroy files.
Security News
PyPI now supports digital attestations, enhancing security and trust by allowing package maintainers to verify the authenticity of Python packages.
Security News
GitHub removed 27 malicious pull requests attempting to inject harmful code across multiple open source repositories, in another round of low-effort attacks.