vite-plugin-beasties

0.4.2 verified Mon Apr 27 auth: no javascript

A Vite plugin that uses the beasties library to automatically identify, inline, and prune critical CSS in HTML pages during build. Current stable version is 0.4.2, with active development and monthly releases. Key differentiators: integrates directly with Vite's transformIndexHtml hook, supports multiple preload strategies (swap, media, JS-based), can prune inlined styles from external CSS files, and respects Vite's public path handling. Compared to critters or other critical CSS tools, it offers a more seamless Vite integration and broader preload strategy options.

Common errors

error Cannot find module 'beasties' ↓

cause Missing or unmet peer dependency for beasties

fix

npm install -D beasties

error beasties is not a function ↓

cause Default import used instead of named import

fix

import { beasties } from 'vite-plugin-beasties'

error ENOENT: no such file or directory, open '/path/to/style.css' ↓

cause CSS file referenced in HTML is missing or not resolved by Vite

fix

Ensure the CSS file exists and is included in Vite's build pipeline

Warnings

breaking v0.4.0 now uses postcss-safe-parser to parse mangled CSS; may change behavior for malformed CSS. ↓

fix Ensure your CSS is valid or test with postcss-safe-parser.

deprecated Options passed directly to beasties() are deprecated as of v0.3.0; use nested `options` object. ↓

fix Move beasties options into the `options` property.

gotcha The plugin only applies during Vite's build, not dev server. ↓

fix Use a separate approach for dev (e.g., critical CSS loader).

gotcha pruneSource deletes inlined CSS from external stylesheets; ensure you have backups. ↓

fix Set pruneSource: false if you want to keep original stylesheets.

Install

npm install vite-plugin-beasties

yarn add vite-plugin-beasties

pnpm add vite-plugin-beasties

Imports

beasties

wrong

import beasties from 'vite-plugin-beasties'

correct

import { beasties } from 'vite-plugin-beasties'

Named export, not default. Must use destructured import.

VitePluginBeastiesOptions
```
import type { VitePluginBeastiesOptions } from 'vite-plugin-beasties'
```
Type import for plugin options; available in TypeScript.

require('vite-plugin-beasties')

wrong

const beasties = require('vite-plugin-beasties')

correct

const { beasties } = require('vite-plugin-beasties')

CommonJS users must destructure the named export.

Quickstart

Configures vite-plugin-beasties with swap preload strategy, source pruning, and 4KB inline threshold.

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

export default defineConfig({
  plugins: [
    beasties({
      options: {
        preload: 'swap',
        pruneSource: true,
        inlineThreshold: 4000
      },
      filter: (path) => path.endsWith('.html')
    })
  ]
})