rollup-plugin-htmlvue

1.2.2 verified Fri May 01 auth: no javascript

Rollup plugin (v1.2.2, last updated Jan 2024) that imports HTML snippets, SVGs, and other XML-parseable markup as Vue single-file components. Works with both Vue 2 and 3 by generating a virtual SFC that is then compiled by rollup-plugin-vue. Key differentiators: supports functional components and v-once/v-pre directives via options; include/exclude patterns using rollup/pluginutils; ships TypeScript types. Unlike generic raw-loaders, this plugin allows using SVG files directly as Vue components with full reactivity support.

Common errors

error Error [ERR_REQUIRE_ESM]: require() of ES Module not supported ↓

cause Using require() in a CommonJS context to import rollup-plugin-htmlvue, which is ESM-only.

fix

Use import syntax: import htmlvue from 'rollup-plugin-htmlvue' or switch to ESM (type:"module").

error You may need an appropriate loader to handle this file type, currently no loaders are configured to process this file ↓

cause Rollup cannot parse the .html file because rollup-plugin-htmlvue is not included in plugins list.

fix

Add htmlvue() to your Rollup plugins array.

error ERROR: The template root requires exactly one element ↓

cause The HTML file contains more than one root-level element.

fix

Wrap all elements in a single root element, e.g., <div></div>.

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

cause rollup-plugin-vue is not installed; it's a required peer dependency.

fix

Install rollup-plugin-vue: npm i -D rollup-plugin-vue.

Warnings

breaking The plugin is ESM-only; attempts to require() it will fail. ↓

fix Use import syntax or set type: 'module' in package.json.

gotcha Template in the HTML file must contain exactly one root element; otherwise Vue compilation fails. ↓

fix Wrap multiple elements in a single parent <div> or <template>.

gotcha Plugin does not compile Vue SFC itself — requires rollup-plugin-vue to be added before htmlvue in plugins array. ↓

fix Ensure vue() plugin is placed before htmlvue() in the plugins list.

deprecated Options 'functional' and 'inheritListeners' are only for Vue 2; they are ignored in Vue 3. ↓

fix Omit these options when targeting Vue 3, or use Vue 2 documentation for functional components.

gotcha Including .vue files via include pattern will produce unexpected results because the plugin expects plain HTML/XML, not Vue SFC. ↓

fix Restrict include pattern to .html, .svg, .xml, or custom non-vue extensions.

Install

npm install rollup-plugin-htmlvue

yarn add rollup-plugin-htmlvue

pnpm add rollup-plugin-htmlvue

Imports

htmlvue

wrong

const htmlvue = require('rollup-plugin-htmlvue')

correct

import htmlvue from 'rollup-plugin-htmlvue'

ESM-only; default export. Require will fail with ERR_REQUIRE_ESM.

rollup-plugin-htmlvue (type import)
wrong
```
import { Options } from 'rollup-plugin-htmlvue'
```
correct
```
import type { Options } from 'rollup-plugin-htmlvue'
```
Options type is a named export; use with `import type` for correct TypeScript usage.
Vue SFC (via HTML import)
wrong
```
import MyComponent from 'rollup-plugin-htmlvue'
```
correct
```
import MyComponent from './my-component.html'
```
The plugin transforms .html files into Vue components after configuration; import paths are relative to the source file, not the package itself.

Quickstart

Shows minimal Rollup config to use htmlvue with vue plugin, and how to import an HTML file as a Vue component.

// rollup.config.js
import vue from 'rollup-plugin-vue'
import htmlvue from 'rollup-plugin-htmlvue'

export default {
  input: 'src/main.js',
  output: {
    dir: 'dist',
    format: 'esm'
  },
  plugins: [
    vue(),
    htmlvue()
  ]
}

// src/MyButton.html
<template>
  <button>Click me</button>
</template>

// src/main.js
import MyButton from './MyButton.html' // Vue SFC as default export
console.log(MyButton) // Component object