rollup-plugin-posthtml

1.1.0 verified Mon Apr 27 auth: no javascript

Rollup plugin to process HTML files using PostHTML. Current stable version is 1.1.0 (released sporadically, no fixed cadence). It integrates PostHTML into the Rollup build pipeline, allowing HTML transformation via PostHTML plugins. Unlike generic HTML loaders, it passes options directly to PostHTML's .process method, supports include/exclude patterns, and can emit files as Rollup assets. Suitable for projects that need to transform HTML with PostHTML plugins during Rollup bundling.

Common errors

error Error: Could not resolve 'posthtml-include' from 'rollup-plugin-posthtml' ↓

cause Missing PostHTML plugin dependency in user's project.

fix

Install the PostHTML plugin: npm install posthtml-include --save-dev

error TypeError: rollupPluginPosthtml is not a function ↓

cause Using named import instead of default import.

fix

Use default import: import rollupPluginPosthtml from 'rollup-plugin-posthtml'

error The 'options' argument must not be an array ↓

cause Passing an array of plugins directly as options instead of object with 'plugins' key.

fix

Wrap plugins in an object: rollupPluginPosthtml({ plugins: [...] })

Warnings

gotcha Options are passed directly to PostHTML's .process method, so options like 'plugins', 'parser', etc. are PostHTML-specific, not Rollup plugin options. ↓

fix Consult PostHTML documentation for valid options; do not pass Rollup plugin options like 'output' to the options object.

gotcha The plugin only processes files that are imported or loaded in the Rollup bundle. HTML files not referenced by any module will not be processed. ↓

fix Ensure your HTML files are imported or use Rollup's plugin configuration to handle them as entry points.

deprecated The plugin's option 'emitFiles' (v1.0.0) was replaced by a built-in 'emit' feature in v1.1.0. ↓

fix Upgrade to v1.1.0 and remove custom emit logic; use the plugin's built-in file emission.

breaking In v1.1.0, the plugin started emitting files as Rollup assets by default. This may cause unexpected output files if you were not expecting it. ↓

fix Set option 'emit: false' if you do not want automatic file emission.

Install

npm install rollup-plugin-posthtml

yarn add rollup-plugin-posthtml

pnpm add rollup-plugin-posthtml

Imports

default

wrong

import { rollupPluginPosthtml } from 'rollup-plugin-posthtml'

correct

import rollupPluginPosthtml from 'rollup-plugin-posthtml'

Package exports a single default function. Named import will fail.

default

wrong

const { rollupPluginPosthtml } = require('rollup-plugin-posthtml')

correct

const rollupPluginPosthtml = require('rollup-plugin-posthtml')

CommonJS require returns the default exported function directly.

rollupPluginPosthtml
```
import rollupPluginPosthtml from 'rollup-plugin-posthtml'
```
The function is typically used as a plugin in Rollup config.

Quickstart

Example Rollup config using rollup-plugin-posthtml with custom PostHTML plugins and include pattern.

import rollupPluginPosthtml from 'rollup-plugin-posthtml';
import posthtml from 'posthtml';
import include from 'posthtml-include';

export default {
  input: 'src/index.js',
  plugins: [
    rollupPluginPosthtml({
      plugins: [
        include()
      ],
      include: '**/*.html'
    })
  ],
  output: {
    dir: 'dist',
    format: 'esm'
  }
};