Skip to content

Commit e74d9c6

Browse files
anaskimAna Sollano Kim
anaskim
and
Ana Sollano Kim
authored
[HTML Modules] Add document to compare proposal examples (#1172)
* Add document for sample code proposals * Add sample code for Rob Eisenberg's proposal of HTML Modules * Add sample code for Microsoft's previous HTML Modules explainer * Add key characteristics for Microsoft's previous proposal * Add key characteristics of Rob Eisenberg's proposal and differences between both proposals * nits * Addressing feedback I.A * Addressing feedback I.B * Addressing feedback II --------- Co-authored-by: Ana Sollano Kim <ansollan@microsoft.com>
1 parent e8cf0e4 commit e74d9c6

1 file changed

Lines changed: 220 additions & 0 deletions

File tree

‎HTMLModules/demo/proposals-sample-code.md‎

Lines changed: 220 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,220 @@
1+
# Comparing proposals
2+
## Authors:
3+
- [Ana Sollano Kim](https://github.com/anaskim)
4+
- [Jayson Chen](https://github.com/ja-y-son)
5+
6+
## Last updated:
7+
October 2025
8+
9+
## Status:
10+
Draft
11+
12+
## Microsoft's previous proposal
13+
Taken from [HTML Modules Explainer](https://github.com/WICG/webcomponents/blob/gh-pages/proposals/html-modules-explainer.md)
14+
15+
### HTML module sample code
16+
17+
```html
18+
<resource-1 id="resource1">...</resource-1>
19+
<resource-2>...</resource-2>
20+
21+
<!--Exporting resources via inline script-->
22+
<script type="module">
23+
// Use `import.meta.document`
24+
let resource = import.meta.document.getElementById("resource1");
25+
export { resource }
26+
</script>
27+
```
28+
29+
or just
30+
31+
```html
32+
<!--Default export-->
33+
<resource-1 id="resource1">...</resource-1>
34+
```
35+
36+
**Importing resources:**
37+
38+
ES Module syntax
39+
40+
```js
41+
import { content } from "./module.html" with { type: "html" };
42+
```
43+
44+
and
45+
46+
```js
47+
// For default exports
48+
import Resource1 from "./module.html" with { type: "html" };
49+
let resource = Resource1.getElementById("resource1");
50+
```
51+
52+
### Key characteristics of the proposal
53+
- Uses import attributes syntax.
54+
- Follows normal HTML5 parsing rules.
55+
- Only allows `<script type="module>"` inside HTML modules (non-module scripts cause failure).
56+
- Introduces `import.meta.document` property for inline module scripts that refers to the HTML Module document.
57+
- Offers a way for an HTML Module to specify its exports using inline script elements. They can export elements, classes, or functions.
58+
- If no script specifies a default export, the entire HTML document becomes the default export.
59+
- Does not support declarative exports.
60+
- Imports resources using the ES Module syntax.
61+
62+
## Rob Eisenberg's proposal
63+
Taken from [HTML Modules and Declarative Custom Elements Proposal](https://gist.github.com/EisenbergEffect/8ec5eaf93283fb5651196e0fdf304555#html-modules).
64+
65+
### HTML module sample code
66+
67+
```html
68+
<!DOCTYPE html>
69+
<html lang="en">
70+
<head>
71+
<meta charset="utf-8">
72+
</head>
73+
<body>
74+
<resource-1>...</resource-1>
75+
<resource-2>...</resource-2>
76+
<resource-3>...</resource-3>
77+
</body>
78+
</html>
79+
```
80+
81+
or
82+
83+
```html
84+
<resource-1>...</resource-1>
85+
<resource-2>...</resource-2>
86+
<resource-3>...</resource-3>
87+
```
88+
89+
**Exporting resources:**
90+
91+
```html
92+
<!--Default export-->
93+
<resource-1 export>...</resource-1>
94+
95+
<!--Named export as Resource2-->
96+
<resource-2 export id="Resource2">...</resource-2>
97+
98+
<!--Not exported-->
99+
<resource-3>...</resource-3>
100+
```
101+
102+
Script within an HTML Module can look up resources via
103+
104+
```js
105+
import.meta.document.getElementById(...)
106+
```
107+
108+
**Importing resources:**
109+
110+
ES Module syntax
111+
112+
```js
113+
import Resource1, { Resource2 } from "./module.html" with { type: "html" };
114+
```
115+
116+
HTML document
117+
118+
```html
119+
<import src="./module.html#Resource2">
120+
```
121+
122+
**Note:** A [`<link>`](https://html.spec.whatwg.org/multipage/semantics.html#the-link-element) element with a new [`rel`](https://html.spec.whatwg.org/multipage/semantics.html#attr-link-rel) type can be used instead of introducing the `<import>` element.
123+
124+
```html
125+
<link href="./module.html#Resource2" rel="module" type="text/html" />
126+
```
127+
128+
### Key characteristics
129+
- Introduces HTML Modules as a new type of HTML "document" that contains exportable resource definitions. These can be imported into HTML documents, other HTML Modules, and/or ES Modules.
130+
- Offers a declarative format for exporting HTML resources via the `export` attribute.
131+
- Imports resources using both ES Module syntax and also declaratively via a new element `<import src="...">`
132+
- Proposes that all nodes are exported as a `DocumentFragment`, except for `<template>`, `<style>`, `<element>` (new), `<registry>` (new).
133+
134+
## Notable differences
135+
1. Microsoft's previous proposal defines only an imperative way to export resources, while Rob Eisenberg's proposal introduces a declarative version.
136+
137+
### Microsoft's previous proposal to export resources imperatively
138+
139+
```html
140+
<resource-1 id="resource1">...</resource-1>
141+
142+
<!--Exporting resources via inline script-->
143+
<script type="module">
144+
// Use `import.meta.document`
145+
let resource = import.meta.document.getElementById("resource1");
146+
export { resource }
147+
</script>
148+
```
149+
150+
### Rob Eisenberg's proposal to export resources declaratively
151+
152+
```html
153+
<!--Default export-->
154+
<resource-1 export>...</resource-1>
155+
156+
<!--Named export as Resource2-->
157+
<resource-2 export id="Resource2">...</resource-2>
158+
```
159+
160+
2. Microsoft's previous proposal relies on ES Module syntax for importing resources, while Rob Eisenberg's proposal introduces a new `<import>` element (which may be replaced with a `<link rel="module" type="text/html" />` element).
161+
3. Both proposals support default exports via different approaches:
162+
163+
### Microsoft's previous proposal for default exports
164+
#### Export
165+
166+
```html
167+
<resource-1 id="resource1">...</resource-1>
168+
```
169+
170+
#### Import
171+
```js
172+
import Resource1 from "./module.html" with { type: "html" };
173+
```
174+
175+
### Rob Eisenberg's proposal for default exports
176+
#### Export
177+
```html
178+
<resource-1 export>...</resource-1>
179+
```
180+
181+
#### Import
182+
In JS
183+
184+
```js
185+
import Resource1 from "./module.html" with { type: "html" };
186+
```
187+
188+
In HTML
189+
190+
```html
191+
<import from="./module.html"></import>
192+
```
193+
194+
## Open questions
195+
- Do we have an imperative export use case? If we can export declaratively, does it make sense to keep looking into imperative export?
196+
- Do we need new `<!DOCTYPE>`? Does it make sense to separate module use cases from normal HTML? In other words, unless the HTML file is declared as a module file, no export will be made and it will be treated as normal html.
197+
- On scripts:
198+
- For most simple use cases, are `<script>` elements necessary? Can we include them in the next stage of this feature?
199+
- Should `<script>` elements be allowed to import other modules?
200+
- On usage:
201+
- Imperatively: Do we import the module/custom element and treat it as `HTMLElement` classes?
202+
203+
```js
204+
import { content } from "./module.html" with { type: "html" };
205+
customElements.define('custom', content);
206+
```
207+
208+
- Declaratively: Do we use a [`<link>`](https://html.spec.whatwg.org/multipage/semantics.html#the-link-element) element and by default assume all the custom elements defined are available to use using their specifier?
209+
210+
```html
211+
<!--html_module.html-->
212+
<div export specifier="custom-element">
213+
<h1>title></h1>
214+
<h1>super cool title</h1>
215+
</div>
216+
217+
<!--index.html-->
218+
<link ref="./html_module.html" rel="html-module">
219+
<custom-element></custom-element> <!--available!!!-->
220+
```

0 commit comments

Comments
 (0)