rollup-plugin-html-modules
v0.1.0-pre.1
Published
Rollup support for the HTML modules proposal
Downloads
7
Readme
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-modulesExample 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(defaultfalse) - Outputs exports in the generated JavaScript module that correspond to elements withidattributes 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.