HTML Modules Rewriter
Last updated 9 months ago by samthor .
Apache-2.0 · Repository · Original npm · Tarball · package.json
$ cnpm install html-modules-polyfill 
SYNC missed versions from official npm registry.

Rewrites HTML Modules, as proposed here, to equivalent JS modules. This can enable use of HTML Modules inside a build system or in a development environment: as of August 2019, no browser has a native implementation.


This is published on NPM as html-modules-polyfill. The package exports a single method, rewrite.

const rewrite = require('html-modules-polyfill');

async function build() {
  const htmlModuleSource = `
<div id="blogPost">
<script type="module">
    let blogPost = import.meta.document.querySelector("#blogPost");
    export {blogPost}
  const rewritten = await rewrite(htmlSource);
  // do something

Intended Use

This single method should be used as part of a Rollup plugin, or perhaps to rewrite HTML files when fetched as modules. Run ./demo/rewrite.js to see the output for the demo module.

Example Output

The output of the example above will be a single file (regardless of the number of top-level scripts used) and look like:

const template = document.createElement('template');
const moduleDocument = document.implementation.createHTMLDocument();
template.innerHTML = `
<div id="blogPost">
<script type="module">
    let blogPost = import.meta.document.querySelector("#blogPost");
    export {blogPost}
import.meta.document = moduleDocument;

let blogPost = import.meta.document.querySelector("#blogPost");

export default moduleDocument;
export { blogPost };


The rewriter uses JSDOM and Rollup to find and concatenate every <script type="module"> found in the passed source, as well as providing the top-level import.meta.document to every script in the It does not use Rollup in a general-purpose way: further imports are left alone.


We convert every found <script type="module"> to a "virtual" import that is imported by a single, virtual entrypoint that we dynamically generate, which also includes the HTML template itself. This entrypoint script re-exports everything from each module, in order. We then use Rollup to merge just these virtual imports and the top-level script.

External scripts are imported without re-exporting: i.e., <script type="module src="foo.js"></script> becomes import './foo.js';.

Further Work

Modern browsers provide a unique import.meta to every JS module, so modifying a single file by adding a .document property at run-time is fine.

However, since most further build tools don't understand import.meta.document at all, rewritten HTML Modules that are later concatenated together will override each other's document. We should add a flag to the rewriter to use a local variable name instead (and rewrite usage) so that Rollup and other tools can play nice.

Additionally, there's no source map support. The simplest approach would be to place the source of each virtual file on the same line as where it was found inside the source HTML, and then rewrite Rollup's generated mappings (in the bundle) to point back to the real HTML, rather than the virtual file.

Current Tags

  • 0.1.0                                ...           latest (9 months ago)

1 Versions

  • 0.1.0                                ...           9 months ago
Maintainers (1)
Today 0
This Week 0
This Month 0
Last Day 0
Last Week 0
Last Month 0
Dependencies (2)
Dev Dependencies (2)
Dependents (0)

Copyright 2014 - 2016 © |