Beasties

<p align="center"> <img src="https://i.imgur.com/J0jv1Sz.png" width="240" height="240" alt="beasties"> <h1 align="center">Beasties</h1> </p>

Beasties is a plugin that inlines your app's [critical CSS] and lazy-loads the rest. It is a maintained fork of GoogleChromeLabs/critters

beasties

It's a little different from other options, because it doesn't use a headless browser to render content. This tradeoff allows Beasties to be very fast and lightweight. It also means Beasties inlines all CSS rules used by your document, rather than only those needed for above-the-fold content. For alternatives, see Similar Libraries.

Beasties' 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, combining to dramatically improve first paint time for most Single Page Applications.

Features

• Fast - no browser, few dependencies
• Integrates with Webpack [beasties-webpack-plugin]
• Supports preloading and/or inlining critical fonts
• Prunes unused CSS keyframes and media queries
• Removes inlined CSS rules from lazy-loaded stylesheets

Installation

First, install Beasties as a development dependency:

npm i -D beasties

or

yarn add -D beasties

Simple Example

import Beasties from 'beasties'

const beasties = new Beasties({
  // optional configuration (see below)
})

const html = `
  <style>
    .red { color: red }
    .blue { color: blue }
  </style>
  <div class="blue">I'm Blue</div>
`

const inlined = await beasties.process(html)

console.log(inlined)
// "<style>.blue{color:blue}</style><div class=\"blue\">I'm Blue</div>"

Usage with Vite

Beasties can be used with Vite through vite-plugin-beasties.

Just add it to your Vite configuration:

// vite.config.ts
import { defineConfig } from 'vite'
import { beasties } from 'vite-plugin-beasties'

export default defineConfig({
  plugins: [
    beasties({
      // optional beasties configuration
      options: {
        preload: 'swap',
      }
    })
  ]
})

The plugin will process the output for your index.html and inline critical CSS while lazy-loading the rest.

Usage with webpack

Beasties is also available as a Webpack plugin called beasties-webpack-plugin.

The Webpack plugin supports the same configuration options as the main beasties package:

// webpack.config.js
+const Beasties = require('beasties-webpack-plugin');

module.exports = {
  plugins: [
+    new Beasties({
+      // optional configuration
+      preload: 'swap',
+    })
  ]
}

That's it! The resultant html will have its critical CSS inlined and the stylesheets lazy-loaded.

Usage

<!-- Generated by documentation.js. Update this documentation by updating the source code. -->

Beasties

All optional. Pass them to new Beasties({ ... }).

Parameters

• options

Properties

• path String Base path location of the CSS files (default: '')
• publicPath String Public path of the CSS resources. This prefix is removed from the href (default: '')
• external Boolean Inline styles from external stylesheets (default: true)
• remote Boolean Download and inline remote stylesheets (http://, https://, //) (default: false)
• inlineThreshold Number Inline external stylesheets smaller than a given size (default: 0)
• minimumExternalSize Number If the non-critical external stylesheet would be below this size, just inline it (default: 0)
• pruneSource Boolean Remove inlined rules from the external stylesheet (default: false)
• mergeStylesheets Boolean Merged inlined stylesheets into a single <style> tag (default: true)
• additionalStylesheets Array<String> Glob for matching other stylesheets to be used while looking for critical CSS.
• reduceInlineStyles Boolean Option indicates if inline styles should be evaluated for critical CSS. By default inline style tags will be evaluated and rewritten to only contain critical CSS. Set it to false to skip processing inline styles. (default: true)
• allowRules Array<String | RegExp> Always include rules matching these selectors or patterns in the critical CSS, regardless of whether they match elements in the document. (default: [])
• preload String Which preload strategy to use
• noscriptFallback Boolean Add <noscript> fallback to JS-based strategies
• inlineFonts Boolean Inline critical font-face rules (default: false)
• preloadFonts Boolean Preloads critical fonts (default: true)
• fonts Boolean Shorthand for setting inlineFonts + preloadFonts* Values:
  • true to inline critical font-face rules and preload the fonts
  • false to don't inline any font-face rules and don't preload fonts
• keyframes String Controls which keyframes rules are inlined.* Values:
  • "critical": (default) inline keyframes rules used by the critical CSS
  • "all" inline all keyframes rules
  • "none" remove all keyframes rules
• compress Boolean Compress resulting critical CSS (default: true)
• safeParser Boolean Use PostCSS safe parser for fault-tolerant CSS parsing. Handles legacy code with syntax errors (default: true)
• logLevel String Controls log level of the plugin (default: "info")
• logger object Provide a custom logger interface logger

Include/exclude rules

We can include or exclude rules to be part of critical CSS by adding comments in the CSS

Single line comments to include/exclude the next CSS rule

/* beasties:exclude */
.selector1 {
  /* this rule will be excluded from critical CSS */
}

.selector2 {
  /* this will be evaluated normally */
}

/* beasties:include */
.selector3 {
  /* this rule will be included in the critical CSS */
}

.selector4 {
  /* this will be evaluated normally */
}

Including/Excluding multiple rules by adding start and end markers

/* beasties:exclude start */

.selector1 {
  /* this rule will be excluded from critical CSS */
}

.selector2 {
  /* this rule will be excluded from critical CSS */
}

/* beasties:exclude end */

/* beasties:include start */

.selector3 {
  /* this rule will be included in the critical CSS */
}

.selector4 {
  /* this rule will be included in the critical CSS */
}

/* beasties:include end */

Programmatically including rules with allowRules

In addition to comment-based inclusion, you can use the allowRules option to programmatically include specific selectors or patterns in the critical CSS, regardless of whether they match elements in the document. This is useful for cases where you know certain styles should always be included.

const beasties = new Beasties({
  // Always include these selectors in critical CSS
  allowRules: [
    // Exact selector match
    '.always-include',
    // Regular expression pattern
    /^\.modal-/
  ]
})

With this configuration, any CSS rules with selectors that match .always-include exactly or start with .modal- will be included in the critical CSS, even if no matching elements exist in the document.

Beasties container

By default Beasties evaluates the CSS a