rollup-plugin-posthtml-template

1.3.0 verified Mon Apr 27 auth: no javascript

A Rollup plugin that imports HTML files as strings and optionally transforms them with PostHTML. Version 1.3.0 is the latest stable release. It enables importing .html files directly in JavaScript, supports custom PostHTML plugins (e.g., posthtml-include), template interpolation, custom parsers (e.g., sugarml), and directives. Differentiators: lightweight, focuses on PostHTML integration for HTML transformations within Rollup builds, with first-class TypeScript support.

Common errors

error Error: Cannot find module 'rollup-plugin-posthtml-template' ↓

cause Package not installed or missing from node_modules.

fix

Run: npm install rollup-plugin-posthtml-template --save-dev

error TypeError: posthtml is not a function ↓

cause Attempting to use posthtml as a named export instead of default export.

fix

Use: import posthtml from 'rollup-plugin-posthtml-template' (default import)

error Error: Cannot find module 'posthtml' (or 'rollup') ↓

cause Peer dependency not installed.

fix

Install missing peer dependencies: npm install posthtml rollup --save-dev

error export 'default' (imported as 'posthtml') was not found in 'rollup-plugin-posthtml-template' ↓

cause Using CommonJS require in an ESM context or vice versa.

fix

Ensure the project uses ESM (type: "module" in package.json) and import syntax.

Warnings

gotcha Plugin requires peer dependencies 'rollup' and 'posthtml'. Missing them or mismatched versions causes silent failures. ↓

fix Install both: npm install rollup posthtml --save-dev

gotcha When using 'template: true', the exported module is a function, not a string. Using it as a string will result in a runtime error. ↓

fix If template option enabled, call the import as a function: `import tmpl from './file.html'; tmpl({ data })`

deprecated The 'parser' option accepting a function is deprecated. Use the PostHTML parser API directly. ↓

fix Pass a string parser name or a PostHTML parser object instead.

gotcha Type definitions are not exported for the options object. Using incorrect options (e.g., 'plugins' with wrong shape) may not trigger TypeScript errors. ↓

fix Refer to the PostHTML documentation for the correct plugin format.

gotcha The plugin does not support Hot Module Replacement (HMR) in development. Changes to HTML files require a manual rebuild. ↓

fix Consider using 'rollup-plugin-hot' or configure your dev server to reload on HTML changes.

Install

npm install rollup-plugin-posthtml-template

yarn add rollup-plugin-posthtml-template

pnpm add rollup-plugin-posthtml-template

Imports

default (posthtml)

wrong

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

correct

import posthtml from 'rollup-plugin-posthtml-template'

Default export, ESM only. Requires “rollup” and “posthtml” as peer dependencies.

RollupPostHTMLTemplateOptions

wrong

import { RollupPostHTMLTemplateOptions } from 'rollup-plugin-posthtml-template' (causing runtime error)

correct

import type { RollupPostHTMLTemplateOptions } from 'rollup-plugin-posthtml-template'

Type import only; not a runtime export.

Plugin (type)
```
import type { Plugin } from 'rollup'
```
The plugin returns a Rollup Plugin object; no additional types exported.

Quickstart

Configures Rollup to import HTML files as strings using the PostHTML plugin.

// rollup.config.js
import posthtml from 'rollup-plugin-posthtml-template';

export default {
  input: 'main.js',
  output: {
    file: 'bundle.js',
    format: 'iife'
  },
  plugins: [
    posthtml()
  ]
};

// main.js
import hello from './hello.html';
document.querySelector('#app').innerHTML = hello;

// hello.html
<p>Hello, World!</p>