README.md

🚨PROJECT STATUS: EXPERIMENTAL🚨This product is in the Experimentation phase. Someone on the team thinks it’s an idea worth exploring, but it may not go any further than this. Use at your own risk.

🍢 HTML Modules Toolkit

Let's face it: if you publish stuff on the web, you probably noticed that
it is getting harder and harder to use HTML to do it. HTML Imports failed to
gain a lot of traction among browser implementors. JavaScript modules are, well,
JavaScript; you can use cool tools like
lit-html within JavaScript, but
traditional markup just isn't on the menu.

HTML has been around for a long time. I mean, sure, just a few decades. But,
that's like a million software years. It is a testament to HTML's versatility
that we still use it for so many things today. The next generation of web
content will need to take advantage of a new generation of HTML capabilities.
HTML Modules Toolkit is a collection of tools and libraries to help web authors
write their apps and content the way they were meant to be written: in highly
declarative HTML. HTML Modules Toolkit unlocks the potential of future HTML
standards for the projects of today.

HTML Modules

There is a nascent standard proposal called
HTML Modules that could
bring actual HTML into a JavaScript module graph near you. This would unlock
crafting modules from HTML, and even loading other HTML-based modules from HTML
documents or JavaScript modules. Importantly, HTML Modules have a lot more
interest from browser implementors than HTML Imports ever did.

HTML Modules aren't standardized yet, but we have a good sense of what they
might look like once they are standard and implemented by browsers.

Future HTML today

HTML Modules Toolkit intends to support workflows that incorporate future HTML
standards like HTML Modules. Today, this project includes transforms for
incorporating HTML Modules into build pipelines, and also middleware for using
HTML Modules seamlessly inside of a dev server.

The standards that this project builds upon are still at a very early stage,
so these tools should be considered to be in a similar state. We will adapt and
improve these libraries to track the related standards as they continue to
solidify.

Installing

npm install @polymer/html-modules-toolkit

What is included

This project includes low-level, versatile string-to-string transforms that can
analyze a file in place, and produce the appropriate ES Module-compatible
output.

You can import these low-level transforms into your Node.js build pipeline or
dev server of choice:

Specifier transforms

If you look closely at the above import statements, you will notice that in some
cases there are separate transforms offered for converting specifiers. This
transform is offered separately because it is not always needed. For example, in
a dev server the server can control the Content-Type of the file being sent,
and can send text/javascript even if the file has a .html file extension.

Usage examples

You can find some concrete usage examples in the
examples/ directory
of this project. The examples include:

Additionally, you can find a live example of the Koa middleware in action on
Glitch.

Contributing

Currently we are only considering features or bugfixes related to the evolving
HTML Modules standard. There is no strict spec text for this standard yet, so
feature requests may be redirected to
w3c/webcomponents if they seem
sufficiently novel.