Rollup-plugin-html-modules NPM

rollup-plugin-html-modules

Rollup support for the HTML modules proposal

Warning! This is an extremely experimental package not ready for production use

HTML Modules

HTML modules is a proproposal to allow importing HTML files into JavaScript modules with the import syntax and an import attribute type of 'html'.

HTML modules would be the third non-JavaScript module type in addition to JSON and CSS modules (WASM modules are another proposed module type).

HTML modules allow developers to put HTML content - such as pre-built DOM, templates, and event entire component definitions - into actual HTML files that are parsed by the browser and use that content in JavaScript.

Use cases

Importing static HTML

<header>
  <h1>Hello, HTML modules!</h1>
  <h2>Cool, huh?</h2>
</header>

import doc from './header.html' with {type: 'html'};
const header = doc.querySelector('header');
document.body.append(header);

Importing HTML templates

<template id="article">
  <article>
    <h1>{{title}}</h1>
    {{body}}
  </article>
</template>

Note: HTML doesn't support expressions in templates natively, yet, but JavaScript libraries like Stampino can support this.

import {prepareTemplate} from 'stampino';
import {render} from 'lit';
import doc from './article.html' with {type: 'html'};

const articleTemplate = prepareTemplate(doc.getElementById('article'));

render(
  articleTemplate({
    title: 'Hello, HTML Modules!',
    body: '...',
  }),
  document.body
);

Importing HTML-based "single file components"

Some frameworks like Vue and libaries like Polymer support defining "single file components" in HTML files. While Vue uses a proprietary fork of HTML and JavaScript, a very similar developer experience can be delivered with standard HTML and HTML modules. These definitions can then be imported into JavaScript or HTML.

simple-greeter.html:

<script type="module">
  import 'stampino-element';
</script>

<stampino-element name="simple-greeter" properties="name">
  <style type="adopted-css">
    :host {
      color: blue;
    }
  </style>
  <template>
    <h1>Hello {{ name }}!</h1>
  </template>
</stampino-element>

index.html:

<!doctype html>
<html>
  <head>
    <script type="html" src="./simple-greeter.html"></script>
  </head>
  <body>
    <simple-greeter name="World"></simple-greeter>
  </body>
</html>

With standard HTML modules there would be no required build step for this to work!

Status note: rollup-plugin-html-modules does not support elvaluating scripts yet

Usage

Install

npm i -D rollup-plugin-html-modules

Example Rollup config

import {htmlModules} from 'rollup-plugin-html-modules';

export default {
  input: 'index.js',
  plugins: [htmlModules()],
  output: {
    file: 'bundle.js',
    format: 'esm',
  },
};

Options

htmlModules() takes an options object with one option currently:

exportIds: boolean (default false) - Outputs exports in the generated JavaScript module that correspond to elements with id attributes in the HTML source. This behavior is not settled in the proposal.
Note: HTML ids that aren't valid JavaScript export names are exported as string literal names, which are a feature of native JavaScript, but not supported in some tools like TypeScript.

How it works

rollup-plugin-html-modules transforms HTML files that are imported with a {type: 'html'} import attribute into JavaScript modules that export an HTML Document object parsed from the HTML source.

These input HTML and JavaScript files: index.html:

<header>
  <h1>Hello, HTML modules!</h1>
  <h2>Cool, huh?</h2>
</header>

index.js:

import doc from './header.html' with {type: 'html'};
const header = doc.querySelector('header');
document.body.append(header);

Would be transformed to:

index.html:

const parser = new DOMParser();
const doc = parser.parseFromString(`<header>
  <h1>Hello, HTML modules!</h1>
  <h2>Cool, huh?</h2>
</header>
`, 'text/html');
export default doc;

index.js:

import doc from './header.html';
const header = doc.querySelector('header');
document.body.append(header);

After the transformation, Rollup can bundle the transformed HTML module into the JavaScript bundle(s) as usual.

@parse5/tools parse5

@everything-registry/sub-chunk-2680

0.1.0-pre.1

4 months ago

0.1.0-pre.0

5 months ago