Critters Webpack Plugin

3.0.2 verified Sat Apr 25 auth: no javascript

Webpack plugin that inlines critical CSS and lazy-loads the rest. v3.0.2 is current, based on Critters 0.0.16. It uses JSDOM and css-select for processing, no headless browser, making it fast and lightweight. Supports html-webpack-plugin v4, preload options, font inlining, and pruning of unused keyframes. Differentiators: speed (no browser), integrates seamlessly with webpack-dev-server, and complements prerender-loader for SPA SSR. Release cadence is irregular.

Common errors

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

cause Missing peer dependency html-webpack-plugin

fix

npm install html-webpack-plugin --save-dev

error TypeError: Critters is not a constructor ↓

cause Using ES6 import on CommonJS-only package

fix

Replace import Critters from 'critters-webpack-plugin' with const Critters = require('critters-webpack-plugin')

error Unhandled rejection TypeError: Cannot read property 'getHooks' of null ↓

cause html-webpack-plugin not loaded or version mismatch

fix

Ensure html-webpack-plugin is installed and added before Critters in plugins array

Warnings

deprecated The package is now called critters-webpack-plugin and v2+ is a rewrite. Legacy 1.x is available via `npm i critters-webpack-plugin@legacy`. ↓

fix Upgrade to v3.x. If stuck on 1.x, use `legacy` dist tag.

breaking In v3.0.0, the internal engine switched to JSDOM and css-select v4, which changes CSS parsing behavior and may produce different inlined results. ↓

fix Review inlined CSS output after upgrading. Check for :where selector support added in 0.0.16.

gotcha CommonJS only in v3; ESM import of the package will fail. ↓

fix Use `require('critters-webpack-plugin')` in webpack config. Do not use `import`.

gotcha html-webpack-plugin is a required peer dependency and must be installed manually. ↓

fix Install html-webpack-plugin: npm i -D html-webpack-plugin

deprecated The `includeMatchingStylesheets` option from v2.5.0 is deprecated in favor of Critters' `additionalStylesheets` option (if available) but still works. ↓

fix Use `additionalStylesheets` option if using standalone Critters, or keep using `includeMatchingStylesheets`.

Install

npm install critters-webpack-plugin

yarn add critters-webpack-plugin

pnpm add critters-webpack-plugin

Imports

Critters

wrong

import Critters from 'critters-webpack-plugin'; // ESM not supported in v3

correct

const Critters = require('critters-webpack-plugin');

v3 does not ship ESM; only CommonJS require is supported. Use require in Node/webpack config.

CrittersPlugin

wrong

const { CrittersPlugin } = require('critters-webpack-plugin'); // default export, not named

correct

const CrittersPlugin = require('critters-webpack-plugin');

The package exports a single class as default. Named import does not work.

CrittersWebpackPlugin
```
const Critters = require('critters-webpack-plugin');
new Critters({...});
```
This is the same default export. Use it directly as a constructor.

Quickstart

Shows basic setup of Critters with HtmlWebpackPlugin, using preload swap mode and font preloading.

// webpack.config.js
const Critters = require('critters-webpack-plugin');
const HtmlWebpackPlugin = require('html-webpack-plugin');
module.exports = {
  plugins: [
    new HtmlWebpackPlugin(),
    new Critters({
      preload: 'swap',
      preloadFonts: true,
      includeMatchingStylesheets: ['*.css']
    })
  ]
};