Summary of HTML Modules discussion

html-modules-issue645.md

HTML Modules summary (issue#645)

Initial: Jun. 28, 2017 / Last Update: Aug. 14, 2017

What is this?

This is the summary of the discussion happening for HTML Modules at webcoomponents#645.

There appear to be lots of diverse opinions, and I'll try to capture them, summarize and provide here for catching up with the discussion for all. Note that this document should never be considered official, complete or final. If anything is wrong or lost, please let @TakayoshiKochi know.

What problem are we trying to solve?

We should be crystal clear on what the real problems people are facing. The resulting syntax/semantics will be judged whether it is solving all or which of the problems.

• How do you get your template HTML? (Which is often literally a <template>.)
  • Writing a custom element that authors can include using a single file is a bit tricky only if we use JavaScript.
• What should the authoring and consumption experience for web components be? (about developer ergonomics)
• Can we have some primitive to load non-JS resources (HTML, CSS, maybe JPG, blobs, etc.) without compiling or bundling at development time?
• Can we have something that can import HTML in an ES2015 modules friendly manner, that covers HTML Imports use cases (shares same dependency graph resolution, and de-duplication mechanism, but capable of import/export)?

Note: the current list above still needs further clarification.

What are use cases?

• Loading a template HTML into JavaScript code. (Auther HTML in HTML syntax, but JavaScript wants to access its DOM tree)
• Primitive to construct HTML Imports polyfill

Use cases of HTML Imports

HTML Imports had such use cases below, and hopefully HTML Modules would cover some or all of these.

• Support component definition in a file, in a native way (e.g. Polymer's component definition, Vue.js's single-file-component)
• Scirra' Construct3 (blog post)
• A loading primitive for dependent resources (not restricted to JavaScript source code)

What are (were?) HTML Imports?

Originally HTML Imports were proposed as a part of web components, but could be used for other purpose, such as loading dependent resources dynamically (e.g. page routing).

• A container format for web components definition
  • A single-file can contain HTML Template, style, and scripts, and can have dependencies.
  • Can be distributed in a single URL (e.g. via CDN), and one HTTP round-trip.
  • ex. Polymer components
• An authoring format for web components
• A way to describe dependency for loading resources
  • HTML is a versatile format to describe dependencies, and even HTML Imports allow describing dependency for other HTML Import resources
• Have semantics for running scripts and upgrading custom elements in them
• Could use preload scanner to optimize the loading performance

Technical Requirements for HTML Modules

• Implementable/interoperable among all major browsers
• Built on top of existing ES2015 module system (i.e. do not consider non-JavaScript usage)
• Can use native HTML parser (possibly off main thread)
  • depends on HTML in JS, or JS in HTML discussion?
• have or provide opportunities for optimizing loading resources / time to render pages

Proposals

• Apple's multiple modules per file / import as / template literal function
  • follow-up: Symbol.importer

Options for writing template HTML

Quoting comment from Justin:

1. Pure JS, using either template strings, DOM builder libraries, JSX, etc. (no HTML modules)
2. Logic in JS, template/CSS in HTML: import template from 'template.html'; in the component's module. Maybe event import style from 'styles.css'; is we include CSS modules.
3. Single-file, like Vue and Polymer: JavaScript, HTML and CSS all in one file.

Related but should be discussed separately, non-goals

These appeared in the discussion, but should be solved / discussed separately from HTML Modules, though could be related / dependent on.

• Declarative definition format of web components (for Shadow DOM/Custom Elements) - issue#71
  • useful for server-side rendering and declarative custom elements
• Standardize <template> variables and event handlers
• Client side include
• Multiple inlined modules in a JS module
  • Needs TC39 route first?

What were the problems with HTML Imports

• Duplicate dependency resolution mechanism against ES2015 modules.
• Uses Document as a type for a loaded HTML Import, but some existing APIs had inconsistency (e.g. document.currentScript), and it was never rendered, which were sometimes confusing.
• Had hooks for HTML parser for good or bad - e.g. <script> execution blocks until dependent imports are complete - which is beneficial to overlap loading and script execution, hard to implement exactly in polyfill.

Open Questions/Needs Refinement

• What was wrong with HTML Imports?
• What are exported from HTML Modules?
• What can be imported to HTML Modules?
• HTML in JS, JS in HTML, pros and cons
• How to resolve URL for workers?

References

• dglazkov's original document about HTML Imports and ES Modules
• Web Components Agenda for TPAC 2017
• HTML Modules (presented at BlinkOn7 unconference)
• HTML Modules polyfill
• Document vs DocumentFragment discussion for HTML Imports
• HTML Imports are the best web component

Thanks for this @TakayoshiKochi. 🙏