Skip to main content

@roots/bud-criticalcss

Experimental

This extension is experimental.

This extension generates 'above-the-fold' css from your application styles.

For more information on this technique check out this web.dev article.

Installation

yarn add @roots/bud-criticalcss --dev

Usage

  1. Identify the markup to be used for critical css generation
  2. Enable the extension

Identify source markup

You may use bud.critical.src to specify a URL or a path on disk to the markup that will be used to generate critical styles.

bud.config.mjs
bud.critical.src(`http://example.test`)
bud.config.mjs
bud.critical.src(bud.path('path/to/index.html'))

Or, you may use bud.critical.html to provide the markup directly.

bud.config.mjs
bud.critical.html(`<html>...</html>`)

Enable the extension

You must explicitly call bud.critical.enable to enable the extension.

bud.config.mjs
bud.critical.enable()

Example

bud.config.mjs
export default async bud => {
bud.critical.src(`http://example.test`).enable(bud.isProduction)
}

API

bud.critical.src

Specify the source with a URL:

bud.config.mjs
bud.critical.src(`http://example.test`)

Specify the source with a local filepath:

bud.config.mjs
bud.critical.src(bud.path(`@src`, `template.html`))

bud.critical.html

Specify the markup directly

bud.config.mjs
bud.critical.html(`<html>...</html>`)

bud.critical.width

Specify the width of the browser viewport

bud.config.mjs
bud.critical.width(1920)

bud.critical.height

Specify the height of the browser viewport

bud.config.mjs
bud.critical.height(1080)

bud.critical.extract

Extract critical css from its source file. Extraction is enabled by default but can be disabled by passing false.

bud.config.mjs
bud.critical.extract(false)

bud.critical.ignore

Ignore certain CSS rules or declarations.

bud.config.mjs
bud.critical.ignore({
decl: [/^transition/],
rule: [/^@font-face/],
})

bud.critical.enable

Enable or disable the extension.

It accepts an optional boolean argument. If no argument is provided, the extension will be enabled.

bud.config.mjs
bud.critical.enable()