{"id":22172,"library":"rollup-plugin-posthtml","title":"rollup-plugin-posthtml","description":"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.","status":"active","version":"1.1.0","language":"javascript","source_language":"en","source_url":"https://github.com/tunnckoCore/rollup-plugin-posthtml","tags":["javascript","html","plugin","post","posthtml","postprocess","process","rollup","rollup-plugin"],"install":[{"cmd":"npm install rollup-plugin-posthtml","lang":"bash","label":"npm"},{"cmd":"yarn add rollup-plugin-posthtml","lang":"bash","label":"yarn"},{"cmd":"pnpm add rollup-plugin-posthtml","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core dependency for HTML processing","package":"posthtml","optional":false},{"reason":"Peer dependency; plugin is designed to work with Rollup","package":"rollup","optional":false}],"imports":[{"note":"Package exports a single default function. Named import will fail.","wrong":"import { rollupPluginPosthtml } from 'rollup-plugin-posthtml'","symbol":"default","correct":"import rollupPluginPosthtml from 'rollup-plugin-posthtml'"},{"note":"CommonJS require returns the default exported function directly.","wrong":"const { rollupPluginPosthtml } = require('rollup-plugin-posthtml')","symbol":"default","correct":"const rollupPluginPosthtml = require('rollup-plugin-posthtml')"},{"note":"The function is typically used as a plugin in Rollup config.","wrong":"","symbol":"rollupPluginPosthtml","correct":"import rollupPluginPosthtml from 'rollup-plugin-posthtml'"}],"quickstart":{"code":"import rollupPluginPosthtml from 'rollup-plugin-posthtml';\nimport posthtml from 'posthtml';\nimport include from 'posthtml-include';\n\nexport default {\n  input: 'src/index.js',\n  plugins: [\n    rollupPluginPosthtml({\n      plugins: [\n        include()\n      ],\n      include: '**/*.html'\n    })\n  ],\n  output: {\n    dir: 'dist',\n    format: 'esm'\n  }\n};","lang":"typescript","description":"Example Rollup config using rollup-plugin-posthtml with custom PostHTML plugins and include pattern."},"warnings":[{"fix":"Consult PostHTML documentation for valid options; do not pass Rollup plugin options like 'output' to the options object.","message":"Options are passed directly to PostHTML's .process method, so options like 'plugins', 'parser', etc. are PostHTML-specific, not Rollup plugin options.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure your HTML files are imported or use Rollup's plugin configuration to handle them as entry points.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Upgrade to v1.1.0 and remove custom emit logic; use the plugin's built-in file emission.","message":"The plugin's option 'emitFiles' (v1.0.0) was replaced by a built-in 'emit' feature in v1.1.0.","severity":"deprecated","affected_versions":">=1.0.0 <1.1.0"},{"fix":"Set option 'emit: false' if you do not want automatic file emission.","message":"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.","severity":"breaking","affected_versions":">=1.1.0"}],"env_vars":null,"last_verified":"2026-04-27T00:00:00.000Z","next_check":"2026-07-26T00:00:00.000Z","problems":[{"fix":"Install the PostHTML plugin: npm install posthtml-include --save-dev","cause":"Missing PostHTML plugin dependency in user's project.","error":"Error: Could not resolve 'posthtml-include' from 'rollup-plugin-posthtml'"},{"fix":"Use default import: import rollupPluginPosthtml from 'rollup-plugin-posthtml'","cause":"Using named import instead of default import.","error":"TypeError: rollupPluginPosthtml is not a function"},{"fix":"Wrap plugins in an object: rollupPluginPosthtml({ plugins: [...] })","cause":"Passing an array of plugins directly as options instead of object with 'plugins' key.","error":"The 'options' argument must not be an array"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}