rollup-plugin-critical

1.0.15 verified Fri May 01 auth: no javascript

Rollup plugin for generating critical CSS using the critical package. Version 1.0.15 is current. It integrates with Rollup build process to extract and inline critical CSS for pages defined by URLs or filesystem paths. Key differentiators: supports multiple pages, custom critical configuration, and optional inlining. Ships TypeScript types. Release cadence: occasional updates. Compared to alternatives like critters, this plugin is specifically designed for Rollup/Vite and offers more configuration flexibility.

Common errors

error ERR_REQUIRE_ESM: require() of ES Module /path/to/node_modules/critical/... from /path/to/rollup-plugin-critical/... not supported. ↓

cause The `critical` package is ESM-only, but older versions of rollup-plugin-critical try to require it in CJS.

fix

Upgrade rollup-plugin-critical to v1.0.13+, or switch your project to ESM.

error Module not found: Can't resolve 'rollup-plugin-critical' ↓

cause Missing or outdated package.json exports field; older versions did not have conditional exports.

fix

Update to v1.0.13+ or adjust your import path (e.g., require('rollup-plugin-critical/dist/index.js')).

error TypeError: PluginCritical is not a function ↓

cause Using named import instead of default, or importing from wrong path.

fix

Use default import: import PluginCritical from 'rollup-plugin-critical'.

Warnings

breaking The `minify` option was removed in v1.0.8 due to its removal from critical v4. ↓

fix Remove `minify` from criticalConfig; use an external minifier if needed.

breaking CJS/ESM import may fail for projects with `type: module` before v1.0.13 due to missing conditional exports. ↓

fix Upgrade to v1.0.13 or later.

breaking In v1.0.11 the plugin was bundled as CJS, causing issues in ESM projects. v1.0.12 reverted to CJS default, v1.0.13 added proper conditional exports. ↓

fix Use v1.0.13 or later for both ESM and CJS support.

deprecated The `critical` package is ESM-only since v5; rollup-plugin-critical v1.0.12+ requires Node 14+ and ESM-compatible environment. ↓

fix Ensure your project can handle ESM. Use Node 14+ and set `type: module` in package.json if needed.

gotcha The `css` option in criticalConfig cannot be set manually; it is overridden by the plugin to include the built CSS files. ↓

fix Do not provide `css` in criticalConfig; the plugin handles it.

Install

npm install rollup-plugin-critical

yarn add rollup-plugin-critical

pnpm add rollup-plugin-critical

Imports

PluginCritical
wrong
```
const PluginCritical = require('rollup-plugin-critical')
```
correct
```
import PluginCritical from 'rollup-plugin-critical'
```
Default export; named export also available as rollupPluginCritical. Since v1.0.13, provides conditional exports for ESM and CJS.
rollupPluginCritical
```
import { rollupPluginCritical } from 'rollup-plugin-critical'
```
Named export, same function as default. Use if you prefer named imports.
PluginCriticalOptions
```
import type { PluginCriticalOptions } from 'rollup-plugin-critical'
```
TypeScript type for options object. Available in v1.0.6+.

Quickstart

Basic setup for rollup-plugin-critical to generate critical CSS for multiple pages.

// rollup.config.js
import PluginCritical from 'rollup-plugin-critical';

export default {
  input: 'src/index.js',
  output: {
    dir: 'dist',
    format: 'es',
  },
  plugins: [
    PluginCritical({
      criticalUrl: 'https://example.com',
      criticalBase: './dist',
      criticalPages: [
        { uri: '', template: 'index' },
        { uri: 'about', template: 'about/index' },
      ],
      criticalConfig: {
        inline: false,
        width: 1200,
        height: 1200,
      },
    }),
  ],
};