beasties-webpack-plugin

0.4.2 verified Sat May 09 auth: no javascript

Webpack plugin to inline critical CSS and lazy-load the rest. Version 0.4.2, released semi-regularly. Unlike alternatives like Critical or Penthouse, it does NOT use a headless browser, making it fast and lightweight; instead, it inlines all CSS rules used by the document. It integrates with html-webpack-plugin, supports preloading fonts, pruning unused CSS, and works with webpack-dev-server. Ships TypeScript types. Requires Node ^20.0.0 or >=22.0.0.

Common errors

error Cannot find module 'html-webpack-plugin' ↓

cause Missing peer dependency html-webpack-plugin.

fix

npm install -D html-webpack-plugin

error TypeError: Cannot read properties of undefined (reading 'hooks') ↓

cause html-webpack-plugin not placed before Beasties.

fix

Move new HtmlWebpackPlugin() above new Beasties() in the plugins array.

error Error: No HTML file found. Ensure html-webpack-plugin outputs HTML. ↓

cause HtmlWebpackPlugin is not configured to emit an HTML file.

fix

Add a template or ensure HtmlWebpackPlugin is correctly configured.

error TypeError: Beasties is not a constructor ↓

cause Importing Beasties as a named export instead of default.

fix

Use import Beasties from 'beasties-webpack-plugin' (no braces).

Warnings

breaking Version 0.4.0 introduced postcss-safe-parser for mangled CSS. If your CSS uses non-standard syntax, it may fail to parse correctly. ↓

fix Ensure CSS is valid; or use version <0.4.0 if you rely on lenient parsing.

gotcha Beasties requires html-webpack-plugin v5+. If using v4, it will silently fail. ↓

fix Install html-webpack-plugin@^5.0.0.

gotcha Beasties will not work if html-webpack-plugin is not included in the plugins array before Beasties. ↓

fix Place HtmlWebpackPlugin before Beasties in the plugins array.

gotcha When using webpack-dev-server, changes to CSS may not trigger proper re-inlining. Requires hard refresh. ↓

fix Manually refresh the browser after CSS changes during development.

Install

npm install beasties-webpack-plugin

yarn add beasties-webpack-plugin

pnpm add beasties-webpack-plugin

Imports

BeastiesWebpackPlugin

wrong

const Beasties = require('beasties-webpack-plugin')

correct

import BeastiesWebpackPlugin from 'beasties-webpack-plugin'

Default export. Supports ESM imports as well as CJS require(). Types included.

default

wrong

import { Beasties } from 'beasties-webpack-plugin'

correct

import Beasties from 'beasties-webpack-plugin'

Use default import. Named export does not exist. Common mistake to destructure.

type Options
wrong
```
import { Options } from 'beasties-webpack-plugin'
```
correct
```
import type { Options } from 'beasties-webpack-plugin'
```
Options type is exported for TypeScript users; use 'import type' to avoid runtime inclusion.

Quickstart

Webpack configuration with HtmlWebpackPlugin and BeastiesWebpackPlugin showing common options.

// webpack.config.js
import HtmlWebpackPlugin from 'html-webpack-plugin';
import Beasties from 'beasties-webpack-plugin';

export default {
  plugins: [
    new HtmlWebpackPlugin({
      template: 'src/index.html'
    }),
    new Beasties({
      preload: 'swap',
      preloadFonts: true,
      inlineThreshold: 4096
    })
  ]
};