[6a3a178] | 1 | <p align="center">
|
---|
| 2 | <img src="https://i.imgur.com/J0jv1Sz.png" width="240" height="240" alt="critters-webpack-plugin">
|
---|
| 3 | <h1 align="center">Critters</h1>
|
---|
| 4 | </p>
|
---|
| 5 |
|
---|
| 6 | > Critters is a plugin that inlines your app's [critical CSS] and lazy-loads the rest.
|
---|
| 7 |
|
---|
| 8 | ## critters [![npm](https://img.shields.io/npm/v/critters-webpack-plugin.svg?style=flat)](https://www.npmjs.org/package/critters)
|
---|
| 9 |
|
---|
| 10 | It's a little different from [other options](#similar-libraries), because it **doesn't use a headless browser** to render content. This tradeoff allows Critters to be very **fast and lightweight**. It also means Critters inlines all CSS rules used by your document, rather than only those needed for above-the-fold content. For alternatives, see [Similar Libraries](#similar-libraries).
|
---|
| 11 |
|
---|
| 12 | Critters' design makes it a good fit when inlining critical CSS for prerendered/SSR'd Single Page Applications. It was developed to be an excellent compliment to [prerender-loader](https://github.com/GoogleChromeLabs/prerender-loader), combining to dramatically improve first paint time for most Single Page Applications.
|
---|
| 13 |
|
---|
| 14 | ## Features
|
---|
| 15 |
|
---|
| 16 | - Fast - no browser, few dependencies
|
---|
| 17 | - Integrates with Webpack [critters-webpack-plugin]
|
---|
| 18 | - Supports preloading and/or inlining critical fonts
|
---|
| 19 | - Prunes unused CSS keyframes and media queries
|
---|
| 20 | - Removes inlined CSS rules from lazy-loaded stylesheets
|
---|
| 21 |
|
---|
| 22 | ## Installation
|
---|
| 23 |
|
---|
| 24 | First, install Critters as a development dependency:
|
---|
| 25 |
|
---|
| 26 | ```sh
|
---|
| 27 | npm i -D critters
|
---|
| 28 | ```
|
---|
| 29 |
|
---|
| 30 | or
|
---|
| 31 |
|
---|
| 32 | ```sh
|
---|
| 33 | yarn add -D critters
|
---|
| 34 | ```
|
---|
| 35 |
|
---|
| 36 | ## Usage
|
---|
| 37 |
|
---|
| 38 | ```diff
|
---|
| 39 | + const Critters = require('critters');
|
---|
| 40 |
|
---|
| 41 | + const c = new Critters({
|
---|
| 42 | + // optional configuration (see below)
|
---|
| 43 | + })
|
---|
| 44 | + const res = c.process(html)
|
---|
| 45 | ```
|
---|
| 46 |
|
---|
| 47 | ## Usage with webpack
|
---|
| 48 |
|
---|
| 49 | ```diff
|
---|
| 50 | // webpack.config.js
|
---|
| 51 | +const Critters = require('critters-webpack-plugin');
|
---|
| 52 |
|
---|
| 53 | module.exports = {
|
---|
| 54 | plugins: [
|
---|
| 55 | + new Critters({
|
---|
| 56 | + // optional configuration (see below)
|
---|
| 57 | + })
|
---|
| 58 | ]
|
---|
| 59 | }
|
---|
| 60 | ```
|
---|
| 61 |
|
---|
| 62 | That's it! The resultant html will have its critical CSS inlined and the stylesheets lazy-loaded.
|
---|
| 63 |
|
---|
| 64 | ## Usage
|
---|
| 65 |
|
---|
| 66 | <!-- Generated by documentation.js. Update this documentation by updating the source code. -->
|
---|
| 67 |
|
---|
| 68 | ### Critters
|
---|
| 69 |
|
---|
| 70 | Create a Critters plugin instance with the given options.
|
---|
| 71 |
|
---|
| 72 | **Parameters**
|
---|
| 73 |
|
---|
| 74 | - `options` **Options** Options to control how Critters inlines CSS.
|
---|
| 75 |
|
---|
| 76 | **Examples**
|
---|
| 77 |
|
---|
| 78 | ```javascript
|
---|
| 79 | // webpack.config.js
|
---|
| 80 | module.exports = {
|
---|
| 81 | plugins: [
|
---|
| 82 | new Critters({
|
---|
| 83 | // Outputs: <link rel="preload" onload="this.rel='stylesheet'">
|
---|
| 84 | preload: 'swap',
|
---|
| 85 |
|
---|
| 86 | // Don't inline critical font-face rules, but preload the font URLs:
|
---|
| 87 | preloadFonts: true,
|
---|
| 88 | }),
|
---|
| 89 | ],
|
---|
| 90 | };
|
---|
| 91 | ```
|
---|
| 92 |
|
---|
| 93 | ### Critters
|
---|
| 94 |
|
---|
| 95 | All optional. Pass them to `new Critters({ ... })`.
|
---|
| 96 |
|
---|
| 97 | **Parameters**
|
---|
| 98 |
|
---|
| 99 | - `options`
|
---|
| 100 |
|
---|
| 101 | **Properties**
|
---|
| 102 |
|
---|
| 103 | - `external` **[Boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** Inline styles from external stylesheets _(default: `true`)_
|
---|
| 104 | - `inlineThreshold` **[Number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)** Inline external stylesheets smaller than a given size _(default: `0`)_
|
---|
| 105 | - `minimumExternalSize` **[Number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)** If the non-critical external stylesheet would be below this size, just inline it _(default: `0`)_
|
---|
| 106 | - `pruneSource` **[Boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** Remove inlined rules from the external stylesheet _(default: `true`)_
|
---|
| 107 | - `mergeStylesheets` **[Boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** Merged inlined stylesheets into a
|
---|
| 108 | single \<style\> tag _(default: `true`)_
|
---|
| 109 | - `additionalStylesheets` **[String[]](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** Glob for matching other stylesheets which should be used to evaluate critical CSS _(default: '')_
|
---|
| 110 | - `preload` **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** Which [preload strategy](#preloadstrategy) to use
|
---|
| 111 | - `noscriptFallback` **[Boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** Add `<noscript>` fallback to JS-based strategies
|
---|
| 112 | - `inlineFonts` **[Boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** Inline critical font-face rules _(default: `false`)_
|
---|
| 113 | - `preloadFonts` **[Boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** Preloads critical fonts _(default: `true`)_
|
---|
| 114 | - `fonts` **[Boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** Shorthand for setting `inlineFonts`+`preloadFonts`- Values:
|
---|
| 115 | - `true` to inline critical font-face rules and preload the fonts
|
---|
| 116 | - `false` to don't inline any font-face rules and don't preload fonts
|
---|
| 117 | - `keyframes` **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** Controls which keyframes rules are inlined.- Values:
|
---|
| 118 | - `"critical"`: _(default)_ inline keyframes rules used by the critical CSS
|
---|
| 119 | - `"all"` inline all keyframes rules
|
---|
| 120 | - `"none"` remove all keyframes rules
|
---|
| 121 | - `compress` **[Boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** Compress resulting critical CSS _(default: `true`)_
|
---|
| 122 | - `logLevel` **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** Controls [log level](#loglevel) of the plugin _(default: `"info"`)_
|
---|
| 123 |
|
---|
| 124 | ### LogLevel
|
---|
| 125 |
|
---|
| 126 | Controls log level of the plugin. Specifies the level the logger should use. A logger will
|
---|
| 127 | not produce output for any log level beneath the specified level. Available levels and order
|
---|
| 128 | are:
|
---|
| 129 |
|
---|
| 130 | - **"info"** _(default)_
|
---|
| 131 | - **"warn"**
|
---|
| 132 | - **"error"**
|
---|
| 133 | - **"trace"**
|
---|
| 134 | - **"debug"**
|
---|
| 135 | - **"silent"**
|
---|
| 136 |
|
---|
| 137 | Type: (`"info"` \| `"warn"` \| `"error"` \| `"trace"` \| `"debug"` \| `"silent"`)
|
---|
| 138 |
|
---|
| 139 | ### PreloadStrategy
|
---|
| 140 |
|
---|
| 141 | The mechanism to use for lazy-loading stylesheets.
|
---|
| 142 | _[JS]_ indicates that a strategy requires JavaScript (falls back to `<noscript>`).
|
---|
| 143 |
|
---|
| 144 | - **default:** Move stylesheet links to the end of the document and insert preload meta tags in their place.
|
---|
| 145 | - **"body":** Move all external stylesheet links to the end of the document.
|
---|
| 146 | - **"media":** Load stylesheets asynchronously by adding `media="not x"` and removing once loaded. _[JS]_
|
---|
| 147 | - **"swap":** Convert stylesheet links to preloads that swap to `rel="stylesheet"` once loaded. _[JS]_
|
---|
| 148 | - **"js":** Inject an asynchronous CSS loader similar to [LoadCSS](https://github.com/filamentgroup/loadCSS) and use it to load stylesheets. _[JS]_
|
---|
| 149 | - **"js-lazy":** Like `"js"`, but the stylesheet is disabled until fully loaded.
|
---|
| 150 |
|
---|
| 151 | Type: (default | `"body"` \| `"media"` \| `"swap"` \| `"js"` \| `"js-lazy"`)
|
---|
| 152 |
|
---|
| 153 | ## Similar Libraries
|
---|
| 154 |
|
---|
| 155 | There are a number of other libraries that can inline Critical CSS, each with a slightly different approach. Here are a few great options:
|
---|
| 156 |
|
---|
| 157 | - [Critical](https://github.com/addyosmani/critical)
|
---|
| 158 | - [Penthouse](https://github.com/pocketjoso/penthouse)
|
---|
| 159 | - [webpack-critical](https://github.com/lukeed/webpack-critical)
|
---|
| 160 | - [webpack-plugin-critical](https://github.com/nrwl/webpack-plugin-critical)
|
---|
| 161 | - [html-critical-webpack-plugin](https://github.com/anthonygore/html-critical-webpack-plugin)
|
---|
| 162 | - [react-snap](https://github.com/stereobooster/react-snap)
|
---|
| 163 |
|
---|
| 164 | ## License
|
---|
| 165 |
|
---|
| 166 | [Apache 2.0](LICENSE)
|
---|
| 167 |
|
---|
| 168 | This is not an official Google product.
|
---|
| 169 |
|
---|
| 170 | [critical css]: https://www.smashingmagazine.com/2015/08/understanding-critical-css/
|
---|
| 171 | [html-webpack-plugin]: https://github.com/jantimon/html-webpack-plugin
|
---|