HTML Critical Webpack Plugin

2.1.0 verified Sat Apr 25 auth: no javascript maintenance

Webpack plugin wrapping the critical CSS inliner library (Addy Osmani's 'critical') to automatically extract and inline critical above-the-fold CSS from emitted HTML files. Version 2.1.0 works with Webpack 4/5 and requires Node >=6. It runs after all assets are emitted, making it compatible with HtmlWebpackPlugin and MiniCssExtractPlugin. Uses Puppeteer/Headless Chrome under the hood, so build environments must have necessary OS dependencies. Released sparingly with no recent activity; last version was published in 2019. Differentiates from other CSS inlining plugins by fully leveraging the 'critical' library's feature set (inline, extract, minify, penthouse config) and precise control over viewport dimensions.

Common errors

error Error: Cannot find module 'puppeteer' ↓

cause Puppeteer is a dependency of 'critical' but not automatically installed in some environments.

fix

Run 'npm install puppeteer' or ensure your package manager installs peer dependencies.

error ENOENT: no such file or directory, open '.../dist/index.html' ↓

cause HtmlWebpackPlugin hasn't emitted the HTML file yet because of plugin ordering.

fix

Place HtmlCriticalWebpackPlugin after HtmlWebpackPlugin in the plugins array.

Warnings

gotcha Plugin relies on Puppeteer/Headless Chrome, which requires system dependencies (libnss3, libx11-xcb1, etc.) that may not be present in minimal Docker or CI environments. ↓

fix Ensure your build environment has the necessary packages; see https://github.com/puppeteer/puppeteer/blob/main/docs/troubleshooting.md

gotcha The plugin reads and writes files on disk (base/src/dest), not from Webpack's in-memory compilation. Ensure output files exist before this plugin runs. ↓

fix Place HtmlCriticalWebpackPlugin after HtmlWebpackPlugin and MiniCssExtractPlugin in the plugins array.

deprecated The package has not been updated since 2019 and may not work with Webpack 5's persistent caching or other modern features. ↓

fix Consider alternatives like 'critters-webpack-plugin' or manually running the 'critical' package as a postbuild script.

Install

npm install html-critical-webpack-plugin

yarn add html-critical-webpack-plugin

pnpm add html-critical-webpack-plugin

Imports

HtmlCriticalWebpackPlugin
wrong
```
import HtmlCriticalWebpackPlugin from 'html-critical-webpack-plugin';
```
correct
```
const HtmlCriticalWebpackPlugin = require('html-critical-webpack-plugin');
```
Package does not ship ESM; only CommonJS via require(). This package is intended for Webpack config files which typically use CommonJS.

Quickstart

Full Webpack config showing how to use HtmlCriticalWebpackPlugin after HtmlWebpackPlugin and MiniCssExtractPlugin to inline critical CSS.

const path = require('path');
const HtmlWebpackPlugin = require('html-webpack-plugin');
const MiniCssExtractPlugin = require('mini-css-extract-plugin');
const HtmlCriticalWebpackPlugin = require('html-critical-webpack-plugin');

module.exports = {
  mode: 'production',
  entry: './src/index.js',
  output: {
    path: path.resolve(__dirname, 'dist'),
    filename: 'bundle.js',
  },
  module: {
    rules: [
      {
        test: /\.css$/,
        use: [MiniCssExtractPlugin.loader, 'css-loader'],
      },
    ],
  },
  plugins: [
    new HtmlWebpackPlugin({
      template: './src/index.html',
      filename: 'index.html',
    }),
    new MiniCssExtractPlugin({
      filename: 'styles.css',
    }),
    new HtmlCriticalWebpackPlugin({
      base: path.resolve(__dirname, 'dist'),
      src: 'index.html',
      dest: 'index.html',
      inline: true,
      minify: true,
      extract: true,
      width: 375,
      height: 565,
      penthouse: {
        blockJSRequests: false,
      },
    }),
  ],
};