>;
338 | }
339 | }
340 | ```
341 |
342 | # Changes
343 |
344 | - 2025-05-02: Added changelog to track changes.
345 | - 2025-05-02: Changed `stopPropagation` to `stopImmediatePropagation`.
346 | - 2024-10-17: Added a provider recommendation to safeguard against memory leaks.
347 | - 2024-06-27: Cleaned up proposal overview.
348 | - 2024-04-09: Fixed type inconsistencies.
349 | - 2023-11-04: Moved proposal to candidate status.
350 | - 2023-04-13: Fixed typos.
351 | - 2023-02-03: Renamed `multiple` to `subscribe`.
352 | - 2023-02-03: Updated context object interface description to allow any type as a context.
353 | - 2022-05-20: Fixed typos.
354 | - 2022-04-21: Clarified ordering of `stopPropagation` / `callback`.
355 | - 2021-11-22: Fixed typos.
356 | - 2021-09-01: Cleaned up proposal overview.
357 | - 2021-07-02: Initial draft.
358 |
--------------------------------------------------------------------------------
/proposals/on-demand-definitions.md:
--------------------------------------------------------------------------------
1 | # On-Demand Definitions Protocol
2 |
3 | A protocol for defining custom elements on-demand without relying on top-level
4 | side-effects.
5 |
6 | **Author**: [dgp1130](https://github.com/dgp1130/)
7 |
8 | **Status**: Draft
9 |
10 | **Created**: 2024-11-26
11 |
12 | **Last updated**: 2024-12-16
13 |
14 | ## Background
15 |
16 | Custom elements are defined via the
17 | [`customElements.define`](https://developer.mozilla.org/en-US/docs/Web/API/CustomElementRegistry/define)
18 | API. Defining an element is inherently a side-effectful operation, as it
19 | upgrades all elements with the associated tag name which already exist in the
20 | document.
21 |
22 | Traditionally, the `customElements.define` call is placed adjacent to the custom
23 | element class declaration like so:
24 |
25 | ```javascript
26 | export class MyElement extends HTMLElement {
27 | // ...
28 | }
29 |
30 | customElements.define('my-element', MyElement);
31 | ```
32 |
33 | For the purposes of this protocol, this pattern is considered a "top-level"
34 | custom element definition because the element is defined in the top-level scope.
35 | Any consumer which imports this file will always call `customElements.define`
36 | just by nature of importing it. Code inside functions, classes, or other
37 | constructs which is _not_ executed during the `import` is not considered
38 | "top-level".
39 |
40 | ```javascript
41 | console.log('This is the top-level');
42 |
43 | export function foo() {
44 | console.log('This is also top-level because it is called from the top-level below.');
45 | }
46 | foo(); // Calling `foo` from the top-level.
47 |
48 | export function bar() {
49 | console.log('This is *not* top-level because a consumer needs to explicitly call it after import.');
50 | }
51 | ```
52 |
53 | Defining custom elements in the top-level scope is useful to ensure they are
54 | always defined, but this creates a top-level side-effect which has a few
55 | negative consequences:
56 |
57 | ### Problem 1: Easy to forget to import a custom element
58 |
59 | It is trivially easy to use a custom element while forgetting to import its
60 | definition, meaning there is no guarantee the element will be defined at
61 | runtime.
62 |
63 | ```javascript
64 | document.querySelector('my-element').doSomething();
65 | // ^ Could error: No guarantee `my-element` has been defined.
66 | ```
67 |
68 | Contrast this with:
69 |
70 | ```javascript
71 | import './my-element.js';
72 |
73 | document.querySelector('my-element').doSomething();
74 | // ^ Know `my-element` definition has been loaded.
75 | ```
76 |
77 | An import is necessary to express that this file depends on the definition of
78 | `my-element` as a top-level side-effect from `my-element.js`. This import could
79 | be hundreds or even thousands of lines away from its usage with no clear
80 | association between the two.
81 |
82 | ### Problem 2: Top-level side-effects are not tree shakable
83 |
84 | Consider a file which exports two elements:
85 |
86 | ```javascript
87 | export class MyFirstElement extends HTMLElement {
88 | // ...
89 | }
90 |
91 | customElements.define('my-first-element', MyFirstElement);
92 |
93 | export class MySecondElement extends HTMLElement {
94 | // ...
95 | }
96 |
97 | customElements.define('my-second-element', MySecondElement);
98 | ```
99 |
100 | A consumer of this file can trivially choose to import only `MyFirstElement` xor
101 | `MySecondElement`. It could also run
102 | `document.createElement('my-first-element')` xor
103 | `document.createElement('my-second-element')`. However, any bundler needs to
104 | retain _both_ `customElements.define` calls because they exist in the top-level
105 | scope. This is necessary for correctness (as `MySecondElement` could depend on
106 | `MyFirstElement`) and because a bundler cannot confidently prove that either
107 | element will not used at runtime.
108 |
109 | Any module which imports _any_ symbol from this file is forced to retain _all_
110 | of them in the final JS bundle. This is just one example, but the issue extends
111 | to all usages of all custom elements. In order to safely use a custom element, a
112 | module must import that element, but since doing so typically calls
113 | `customElements.define` in the top-level scope, that element can _never_ be tree
114 | shaken, even if it is ultimately never used. Consider the following dev-mode
115 | only usage of a particular element:
116 |
117 | ```javascript
118 | import './my-element.js';
119 |
120 | // Set to a compile-time constant known by the bundler.
121 | if (import.meta.env.DEV) {
122 | document.querySelector('my-element').doSomething();
123 | }
124 | ```
125 |
126 | Even if a bundler correctly configures the production build such that
127 | `import.meta.env.DEV === false`, it can only remove the `doSomething` call from
128 | the bundle. `import './my-element,js';` still needs to remain due to the global
129 | side-effect it creates and which the bundler cannot prove is unused.
130 |
131 | ### Problem 3: Side-effectful imports are sub-optimal
132 |
133 | Relying on side-effectful imports brings negative consequences. Tooling can not
134 | statically detect whether such an import is required or not. If a future
135 | developer removes `.doSomething()` in the above example, no automated tooling
136 | will instruct them to also remove `import './my-element.js';`. This leads to
137 | extra, unneeded dependencies and reduces confidence for developers who may be
138 | hesitant to remove the import because it is hard to know whether anything in the
139 | module actually does depend on any side-effects from `my-element.js`.
140 |
141 | For human developers, it is in no way obvious that calling `doSomething`
142 | requires an import of `./my-element.js` or that the import exists to provide
143 | `doSomething`. Extensive comments are necessary to communicate the relationship
144 | between these two statements for developers unfamiliar with these constraints.
145 |
146 | ### Problem 4: File ordering
147 |
148 | When forgetting an import on a custom element, using that element is actually
149 | not guaranteed to fail. It only has the _potential_ to fail, which is in many
150 | ways worse. When two JavaScript files do not have any `import`-relationship
151 | between them, which one is actually executed first is ultimately
152 | _unpredictable_.
153 |
154 | The ordering between such files is largely dependent on which other files in the
155 | program import them. Different bundlers may have different behavior and sort
156 | these files completely differently. Normally that's fine: if the files don't
157 | import each other and have no dependency relationship between them, it doesn't
158 | actually matter which one comes first.
159 |
160 | However, side-effects from the first file executed are observable in the second.
161 | Since defining a custom element is inherently a side-effectful operation, there
162 | is a potential file ordering hazard. When one file defines a custom element, and
163 | the other uses that custom element, the system will work only when that ordering
164 | aligns in this unpredictable way.
165 |
166 | ```javascript
167 | // my-element.js
168 |
169 | class MyElement extends HTMLElement {
170 | doSomething() {
171 | console.log('Doing something!');
172 | }
173 | }
174 |
175 | customElements.define('my-element', MyElement);
176 | ```
177 |
178 | ```javascript
179 | // my-user.js
180 |
181 | // Note the absence of an `import` here.
182 |
183 | document.querySelector('my-element').doSomething();
184 | // ^ MIGHT fail.
185 | ```
186 |
187 | The lack of an import between `my-user.js` and `my-element.js` means that this
188 | will work if-and-only-if `my-element.js` happens to be sorted _before_
189 | `my-user.js`, which depends entirely on the bundler implementation in use as
190 | well as other files and import edges in the program. Unrelated refactorings can
191 | change the ordering of these two files and lead to unexpected errors.
192 |
193 | ## Goals
194 |
195 | * Provide a common primitive for custom element libraries and frameworks to
196 | confidently rely on a custom element they don't own being correctly defined.
197 | * Support tree-shakable custom elements.
198 | * More closely couple a custom element's usage with a dependency on its
199 | implementation.
200 | * Improve the ability for standard JavaScript tools (bundlers, type checkers,
201 | linters, etc.) to reason about custom element usage.
202 | * Reduce reliance on side-effects from files not explicitly depended upon.
203 | * Continue to support custom element definition as a top-level side-effect
204 | when necessary.
205 |
206 | ## Non-goals
207 |
208 | * _Do not_ address the problem of identifying and defining
209 | ["entry-point components"](#defining-entry-point-elements).
210 | * _Do not_ remove all top-level side-effects from custom element definitions.
211 | Some may still be necessary.
212 |
213 | ## Overview
214 |
215 | This protocol specifies a static `define` property on custom elements which
216 | calls `customElements.define` if the element has not already been defined. This
217 | allows anything with a reference to a component's class to define that component
218 | "on demand" before using it.
219 |
220 | ### Example
221 |
222 | An element can implement this protocol by specifying a static `define` function:
223 |
224 | ```javascript
225 | export class MyElement extends HTMLElement {
226 | static define() {
227 | // Check if the tag name was already defined by another class.
228 | const existing = customElements.get('my-element');
229 | if (existing) {
230 | if (existing === MyElement) {
231 | return; // Already defined as the correct class, no-op.
232 | } else {
233 | throw new Error(`Tag name \`my-element\` already defined as \`${
234 | existing.name}\`.`);
235 | }
236 | }
237 |
238 | customElements.define('my-element', MyElement);
239 | }
240 | }
241 | ```
242 |
243 | A consumer can use this protocol by checking if the `define` property exists and
244 | calling it before using the element.
245 |
246 | ```javascript
247 | import {MyElement} from './my-element.js';
248 |
249 | MyElement.define();
250 | document.querySelector('my-element').doSomething();
251 | // ^ Always works!
252 | ```
253 |
254 | ## Design detail
255 |
256 | This structure removes usage of `customElements.define` in the top-level scope
257 | and allows web component libraries / frameworks to design APIs which depend on
258 | this primitive.
259 |
260 | ### Framework utilization
261 |
262 | As two small examples, [HydroActive](https://github.com/dgp1130/HydroActive/)
263 | already implements this draft. All `HydroActive` components come with a built-in
264 | `define` implementation and using a component
265 | [requires a reference to its component class](#hydroactive) before making that
266 | component accessible to developers. HydroActive uses this class to automatically
267 | call `define` and ensure they are properly defined being being interacted with
268 | by the developer.
269 |
270 | DISCLAIMER: The author of this proposal is also the maintainer of HydroActive.
271 |
272 | ```javascript
273 | import {component} from 'hydroactive';
274 | import {SomeComp} from './some-comp.js';
275 |
276 | export const MyElement = component('my-element', (host) => {
277 | // `.access(SomeComp)` implicitly calls `SomeComp.define()`.
278 | host.query('some-comp').access(SomeComp).element.doSomething();
279 | });
280 | ```
281 |
282 | This approach provides a guarantee that `SomeComp` is defined before
283 | `doSomething` is called. It also allows `SomeComp` to be tree-shaken from the
284 | bundle if it is not used by `MyElement` or if `MyElement` is itself unused and
285 | eligible for tree-shaking.
286 |
287 | One more potential example would be `lit-html`, which currently relies on
288 | [`lit-analyzer`](#lit-analyzer) to ensure all dependencies of a custom element
289 | have been defined. Lit could hypothetically be updated to use explicit
290 | references to custom element classes:
291 |
292 | ```javascript
293 | import {MyElement} from './my-element.js';
294 |
295 | function renderMyElement() {
296 | return html`
297 | <${MyElement}>Hello, World!
298 | `;
299 | }
300 | ```
301 |
302 | The `html` tagged template literal could implicitly call `MyElement.define()` to
303 | ensure it is defined prior to rendering. This ensures `MyElement` is indeed
304 | defined and allows it to be tree-shaken if `renderMyElement` is itself
305 | tree-shaken.
306 |
307 | ### Benefits
308 |
309 | This protocol fixes or improves all of the above specified problems:
310 |
311 | 1. Removing `customElements.define` from the top-level scope allows bundlers to
312 | effectively tree-shake any unused components. In order to define an element
313 | with `MyElement.define()`, users must have a reference to `MyElement` which
314 | is known to the bundler.
315 | 2. This API provides a common primitive for web component libraries and
316 | frameworks to [build on top of](#framework-utilization). Designing APIs with
317 | this protocol in mind allows compilers and linters to effectively require
318 | that an import is used where necessary.
319 | 3. Similar to 2., web component APIs can
320 | [be designed to leverage this protocol](#framework-utilization) and more
321 | closely associate a web component class with its usage.
322 | 4. Leveraging an import on a custom element class enforces strict ordering and
323 | makes it harder for users of that class to depend on an element prior to its
324 | class' definition.
325 |
326 | ### Compatibility with top-level definitions
327 |
328 | Any usages of a custom element which do require it to be defined at top-level
329 | execution can still be supported by calling `MyElement.define()` at that
330 | location. It is perfectly valid to write:
331 |
332 | ```javascript
333 | export class MyElement extends HTMLElement {
334 | static define() { /* ... */ }
335 |
336 | doSomething() {
337 | console.log('Doing something!');
338 | }
339 | }
340 |
341 | MyElement.define();
342 |
343 | document.querySelector('my-element').doSomething();
344 | ```
345 |
346 | Even though `MyElement.define` is called in the top-level scope, this is still a
347 | correct implementation and usage of the static `define`. Any other consumers of
348 | `MyElement` can call `MyElement.define` to enforce that the element is indeed
349 | defined before they use it, so this is still a useful pattern. The fact that the
350 | element happens to always be defined before any consumers attempt to use it is
351 | an implementation detail those consumers are intentionally abstracting away from
352 | themselves by calling `MyElement.define`.
353 |
354 | ## Open questions
355 |
356 | Some more nuanced questions with this API.
357 |
358 | ### Naming
359 |
360 | The name `define` was chosen for being short, direct, and explicit about what it
361 | does: defining an element in the registry.
362 |
363 | This name might be too short such that developers may want to use the name for
364 | their own purposes. For example, a custom element representing words in a
365 | dictionary may want a `define` function which shows the definition of its word.
366 |
367 | Another challenge is that `define` does not always define its element. If the
368 | associated element is already defined, then the `define` function is technically
369 | a no-op, which can be confusing.
370 |
371 | ```javascript
372 | import { MyElement } from './my-element.js';
373 |
374 | // Defines the element.
375 | MyElement.define();
376 |
377 | // Silently does nothing.
378 | MyElement.define();
379 | ```
380 |
381 | The necessary post-condition for this function is that `MyElement` is defined in
382 | the custom elements registry. Even if the second call technically had no effect,
383 | the outcome is still that `MyElement` is definitely defined.
384 |
385 | Alternatives names may be considered for bike-shedding.
386 |
387 | ### Scoped Custom Element Registries support
388 |
389 | The
390 | [Scoped Custom Element Registries proposal](https://github.com/WICG/webcomponents/blob/gh-pages/proposals/Scoped-Custom-Element-Registries.md)
391 | is not yet finalized and therefore not included in the implementation of this
392 | proposal. However, if and when that proposal is completed, it can be easily
393 | included with a small addition which accepts a custom element registry and a tag
394 | name as input parameters:
395 |
396 | ```javascript
397 | export class MyElement extends HTMLElement {
398 | static define(registry = customElements, tagName = 'my-element') {
399 | // Tag name can only be modified when not in the global registry.
400 | if (registry === customElements && tagName !== 'my-element') {
401 | throw new Error('Cannot use a non-default tag name in the global custom element registry.');
402 | }
403 |
404 | // Check if the tag name was already defined by another class.
405 | const existing = registry.get(tagName);
406 | if (existing) {
407 | if (existing === Clazz) {
408 | return; // Already defined as the correct class, no-op.
409 | } else {
410 | throw new Error(`Tag name \`${tagName}\` already defined as \`${
411 | existing.name}\`.`);
412 | }
413 | }
414 |
415 | // Define the class.
416 | registry.define(tagName, Clazz, options);
417 | }
418 | }
419 |
420 | // Usage:
421 | const registry = new CustomElementRegistry();
422 | MyElement.define(registry);
423 |
424 | // With custom tag name:
425 | MyElement.define(registry, 'my-other-element');
426 | ```
427 |
428 | This implementation registers the custom element on any given registry,
429 | defaulting to the global registry.
430 |
431 | Attempting to define a custom tag name on the global registry still throws in
432 | order to maintain the invariant that all consumers of the global registry use
433 | the agreed-upon name. See [custom tag name](#custom-tag-name).
434 |
435 | ### Scoped Custom Element Registries as an alternative
436 |
437 | Scoped Custom Element Registries have many nice properties which potentially
438 | allow them to serve as an alternative solution to many of the goals of this
439 | proposal.
440 |
441 | Scoped registries do not require global side-effects like a top-level
442 | `customElements.define` call and allow every consumer to create their own
443 | registry and define dependencies at an appropriate time. This enables components
444 | to be tree-shaken when not used.
445 |
446 | ```javascript
447 | class MyElement extends HTMLElement {
448 | // ...
449 | }
450 |
451 | function useMyElement() {
452 | const myRegistry = new CustomElementRegistry();
453 | myRegistry.define('my-element', MyElement);
454 | // ...
455 | }
456 | ```
457 |
458 | However, scoped custom element registries have some drawbacks which make them a
459 | non-ideal solution to this proposal.
460 |
461 | First, scoped registries are coupled to shadow DOM, which not all custom
462 | elements use. This On-Demand Definitions proposal supports all custom elements,
463 | even light DOM components. Note that a
464 | [more recent scoped registry proposal](https://github.com/whatwg/html/issues/10854)
465 | may lift this particular restriction.
466 |
467 | Second, scoped registries require creating an entirely distinct registry with
468 | potentially decoupled tag names. This places a constraint on consumers which
469 | need to manually define a mapping of `some-tag-name` -> `MyElement`. This
470 | constraint is reasonable within the context of a scoped registry, but is
471 | completely unnecessary for the goals of this proposal. Not every consumer of an
472 | element wants its own custom registry or to decouple and own its own mapping of
473 | tag names.
474 |
475 | Third, as shown in
476 | [scoped registries support](#scoped-custom-element-registries-support), this
477 | proposal can support scoped registries and even provides some benefit for them.
478 | Having a `define` function owned by the component author provides an abstraction
479 | over the tag name in the global registry and
480 | [the `options` field](#allowing-options).
481 |
482 | Fourth, scoped registries also require removing the top-level
483 | `customElements.define` call anyways to realize their benefits, which On-Demand
484 | Definitions naturally achieves as well.
485 |
486 | Fifth, some component consumers may use a scoped custom elements registry, but
487 | others may not and should still receive the benefits of this proposal. Using a
488 | scoped registry does not address any of these problems for components in the
489 | global registry, while this On-Demand Definitions proposal does. It is perfectly
490 | valid for two different consumers to call `MyElement.define()` in the global
491 | registry while a third consumer uses a scoped registry. All three receive the
492 | benefits of this proposal.
493 |
494 | For these reasons, scoped registries are not a better solution for the goals of
495 | this proposal.
496 |
497 | ### No-op when already defined
498 |
499 | `define` silently no-ops when its element is already defined, meaning multiple
500 | consumers can safely call `define` without fear of negative effects.
501 |
502 | ALTERNATIVE PROPOSAL: Let `define` throw if the element is already defined and
503 | have callers check `customElements.get` before invoking it.
504 |
505 | Requiring callers to check `customElements.get` means that every usage of
506 | `define` either needs separate knowledge of the element's tag name or needs to
507 | manually call `customElements.getName`, which is extra effort which accomplishes
508 | very little. No user of a custom element can safely assume it is the _only_ user
509 | of that element and unconditionally call `define`.
510 |
511 | ### Custom tag name
512 |
513 | `define` only supports defining the element with one hard-coded tag name. This
514 | behavior is equivalent to calling `customElements.define` in the top-level
515 | scope. Consumers of the class are not able to influence the tag name used.
516 |
517 | ALTERNATIVE PROPOSAL: Let the user provide an optional tag name to give
518 | consumers more flexibility.
519 |
520 | ```javascript
521 | export class MyElement extends HTMLElement {
522 | static define(tagName) {
523 | // ...
524 |
525 | customElements.define(tagName ?? 'my-element', MyElement);
526 | }
527 | }
528 | ```
529 |
530 | Supporting user-defined tag names means a custom element no longer has static
531 | knowledge of its tag name. While some custom element authors may be comfortable
532 | that constraint, it is likely not something this protocol would want to force on
533 | its implementers.
534 |
535 | `customElements.define` throws when given the same class for multiple tag names.
536 | This is an issue when multiple consumers call `MyElement.define` with different
537 | tag names, expecting to safely define their chosen tag name, only to encounter
538 | an error.
539 |
540 | The main goal of this protocol is to allow multiple, unrelated consumers to
541 | safely use a custom element without interfering with each other or relying on
542 | unexpected side-effects. Allowing each consumer to pick its own tag name and
543 | break any other consumer using a different tag name actively fights against the
544 | goals of this protocol.
545 |
546 | ### Allowing options
547 |
548 | The static `define` function does not support any additional options, such as
549 | [the options of `customElements.define`](https://developer.mozilla.org/en-US/docs/Web/API/CustomElementRegistry/define#options).
550 |
551 | ALTERNATIVE PROPOSAL: Allow `options` to be passed through as parameters to
552 | `define`:
553 |
554 | ```javascript
555 | class MyElement extends HTMLElement {
556 | static define(options) {
557 | // ...
558 |
559 | customElements.define('my-element', MyElement, options);
560 | }
561 | }
562 | ```
563 |
564 | Currently, the only option supported by `customElements.define` is
565 | [`extends`](https://developer.mozilla.org/en-US/docs/Web/API/CustomElementRegistry/define#extends)
566 | which allows a custom element to extend an existing built-in tag name and
567 | leverage the
568 | [`is` attribute](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements#using_a_custom_element).
569 |
570 | Whether or not an element extends a built-in class is a decision made by the
571 | author of that element, not its consumers. Allowing consumers to decide the
572 | `extends` option would increase the likelihood of the field being set
573 | incorrectly and encountering unsupported behavior.
574 |
575 | It also raises the question of what happens when two `define` calls disagree on
576 | the option.
577 |
578 | ```javascript
579 | import { MyElement } from './my-element.js';
580 |
581 | export function createParagraph() {
582 | MyElement.define({ extends: 'p' });
583 | return document.createElement('p', {
584 | is: 'my-element',
585 | });
586 | }
587 |
588 | export function createSection() {
589 | MyElement.define({ extends: 'section' });
590 | return document.createElement('section', {
591 | is: 'my-element',
592 | });
593 | }
594 | ```
595 |
596 | Whichever function is called first will dictate the actual `extends` value used.
597 | Meanwhile the other function will find `MyElement` defined with the wrong
598 | `extends` value and its returned element will not be an instance of `MyElement`
599 | as expected. If ordering is non-deterministic or unpredictable, this behavior
600 | can easily lead to bugs.
601 |
602 | Instead, custom element definition options may only be specified within the
603 | `define` function itself, where the component author can control its value.
604 |
605 | ```javascript
606 | class MyElement extends HTMLParagraphElement {
607 | static define() {
608 | // ...
609 |
610 | customElements.define('my-element', MyElement, { extends: 'p' });
611 | }
612 | }
613 | ```
614 |
615 | Future additions to this options object maybe be more appropriate to make
616 | configurable for individual consumers and considered on a case-by-case basis.
617 | However, `customElements.define` is naturally creating a side-effect which
618 | stores the provided component class and its configuration. When multiple
619 | consumers are defining a component on-demand, they need to agree on that
620 | configuration. This implies that no consumer can have direct control over the
621 | configuration or else it would risk breaking other consumers when they are
622 | forced to use a component with a configuration they did not expect. It is highly
623 | unlikely future options introduced to `customElements.define` will support being
624 | independently configurable for multiple consumers, therefore that functionality
625 | is intentionally _not_ exposed.
626 |
627 | ### Defining entry-point elements
628 |
629 | A problem deliberately _not_ solved by this protocol is identification of
630 | "entry-point elements". In this context, an "entry-point element" is one which
631 | must be defined in the top-level scope of some script in order to create a
632 | desired behavior on the page.
633 |
634 | If all custom elements move their definitions into a static `define` and no
635 | script calls any of them from the top-level scope, then _no_ element is ever
636 | defined or upgraded. For example, consider an application with the following
637 | HTML:
638 |
639 | ```html
640 |
641 |
642 |
643 | ```
644 |
645 | Consider also that `MyApp` is defined in line with this protocol, omitting
646 | top-level side-effects:
647 |
648 | ```javascript
649 | // my-app.js
650 |
651 | import {SomeComp} from './some-comp.js';
652 |
653 | export class MyApp extends HTMLElement {
654 | static define() {
655 | // ...
656 | }
657 |
658 | // ...
659 | }
660 |
661 | // No top-level `customElements.define` or `MyApp.define`.
662 | ```
663 |
664 | `my-app.js` _needs_ to call `customElements.define('my-app', MyApp)` /
665 | `MyApp.define()` in its top-level scope in order for the application to start.
666 |
667 | However in this scenario, `MyApp.define` is never called and the entire element,
668 | as well as its dependencies, are never defined or have any effect on the
669 | document.
670 |
671 | This illustrates the need for _some_ custom element to be intentionally defined
672 | in the top-level scope in order to upgrade its element during script execution
673 | as well as define any custom element dependencies it may require. In this case,
674 | something needs to identify `MyApp` as an "entry-point element" which must be
675 | defined in the top-level scope and call `MyApp.define()`. This can be hard-coded
676 | by the developer in the top-level scope of `my-app.js` or handled by some other
677 | tool.
678 |
679 | Identifying entry-point elements, retaining them in the bundle, and triggering
680 | their definition is a complex problem in its own right and out of scope for this
681 | particular proposal.
682 |
683 | ### Development-only checks
684 |
685 | The [example implementation](#example) includes a check which throws if the tag
686 | name was already defined by a different class. This is useful for development
687 | purposes in case of a tag name conflict, However, it is very unlikely to be a
688 | problem in production applications after the developer has resolved any relevant
689 | issues.
690 |
691 | Therefore it is acceptable to omit this particular check and no-op in production
692 | for the case of conflicting class definitions. This enables a small bundle size
693 | improvement without affecting valid usage. A _minimal_ implementation of the
694 | protocol looks like:
695 |
696 | ```javascript
697 | export class MyElement extends HTMLElement {
698 | static define() {
699 | // If already defined, no-op.
700 | // Might be the wrong class, but we don't care in a well-formed application.
701 | if (customElements.get('my-element')) return;
702 |
703 | customElements.define('my-element', MyElement);
704 | }
705 | }
706 | ```
707 |
708 | ### Why not inline the `define` implementation?
709 |
710 | ALTERNATIVE PROPOSAL: The static `define` implementation is relatively small and
711 | condensed, just execute that whenever there is a need to use a custom element.
712 |
713 | ```javascript
714 | import {MyElement} from './my-element.js';
715 |
716 | if (!customElements.get('my-element')) {
717 | customElements.define('my-element', MyElement);
718 | }
719 |
720 | document.querySelector('my-element').doSomething();
721 | ```
722 |
723 | This is functionally equivalent to calling `MyElement.define` but does not
724 | require `MyElement` to opt-in to this community protocol. Inlining `define` does
725 | come with a few costs however.
726 |
727 | First, `MyElement.define` provides an abstraction which encapsulates the tag
728 | name and options passed to `customElements.define`. Without this abstraction, it
729 | becomes more likely multiple consumers will define the same element multiple
730 | times with different choices and run into the same problems as
731 | [allowing options in the static `define` function](#allowing-options) does.
732 |
733 | Second, inlining requires knowledge of the tag name. To call
734 | `customElements.define`, the caller must know the tag name to define. In
735 | general, every consumer of an element likely does need to know the tag name it
736 | is consuming, however libraries or frameworks may want to handle calling
737 | `customElements.define` automatically in a context where they don't necessarily
738 | know the expected tag name and would require a product developer to manually
739 | provide this information every time.
740 |
741 | Third, when given a custom element which has not been defined, is it reasonable
742 | to directly define that element? Most existing custom elements expect a single,
743 | centralized `customElements.define` call and do not anticipate that they may be
744 | defined at any time.
745 |
746 | Consider a component written in the traditional style with an adjacent top-level
747 | side-effect and no knowledge of the On-Demand Definitions protocol or an
748 | equivalent "Just call `customElements.define` before you use it" convention:
749 |
750 | ```javascript
751 | export class MyElement extends HTMLElement {
752 | // ...
753 | }
754 |
755 | doSomething(MyElement);
756 |
757 | customElements.define('my-element', MyElement); // Throws an error.
758 |
759 | function doSomething(elClass) {
760 | // Conditionally define the class if necessary.
761 | if (!customElements.get('my-element')) {
762 | customElements.define('my-element', elClass);
763 | }
764 |
765 | document.querySelector('my-element').doSomethingElse();
766 | }
767 | ```
768 |
769 | Because `doSomething` uses the convention of conditionally defining the element,
770 | it is able to define `MyElement` *before* the adjacent top-level side-effect,
771 | causing it to throw an error. Any code with a reference to `MyElement` prior to
772 | its definition could potentially cause this problem. An unexpected early
773 | definition can also be observed through other `customElements` APIs like `get`,
774 | `getName`, or `whenDefined` which could affect component logic in unanticipated
775 | ways.
776 |
777 | Therefore On-Demand Definitions is better implemented as an opt-in decision by
778 | any given component. By implementing the static `define` function, a component
779 | essentially states: "I do not expect to be defined by a specific, centralized
780 | `customElements.define` call." This guarantee is what allows decentralized
781 | `define` calls to work consistently.
782 |
783 | Fourth, to support tree-shaking, top-level side-effects need to be removed
784 | regardless of whether a separate `define` abstraction is used. This begs the
785 | question: What should a web component author do with their existing
786 | `customElements.define` call? There are a few options:
787 |
788 | 1. Move it to a separate ES module and tell consumers to import that when
789 | top-level side-effects are needed.
790 | 1. Delete it entirely and expect every consumer to follow the convention of
791 | conditionally defining `MyElement` before using it.
792 | 1. Move it into their own (not specified by a community protocol) version of a
793 | static `defineMyComponent` function with none of the interoperability
794 | benefits.
795 |
796 | These each have their own trade offs and every component author is likely to
797 | make an independent decision leading to divergence within the web component
798 | space. This makes consuming web components even harder because consumers have to
799 | ask "How do I ensure this component is defined?" every time they adopt a new
800 | custom element.
801 |
802 | On-Demand Definitions provides a recommended answer to this complicated question
803 | which maximizes compatibility with the rest of the ecosystem.
804 |
805 | Finally, there is a small bundle size and stability argument to make here.
806 | Conditionally defining a custom element is not quite trivial and has a few
807 | unexpected edge cases (ex. the component is already defined but with a different
808 | class). The fewer times this function is implemented, the less likely bugs will
809 | be introduced and the less JavaScript users need to download. Also components
810 | are likely to be consumed more frequently than they will be implemented.
811 | Therefore it follows that it will be slightly more optimal for component
812 | definitions to implement `define` rather than asking every consumer of the
813 | component to implement conditional define logic itself.
814 |
815 | Note that custom element libraries and frameworks do skew this reasoning
816 | slightly, however the general rule of component usage (even if implemented by a
817 | small number of frameworks) outnumbering component definitions (even if also
818 | implemented by a small number of frameworks) should hold in most environments.
819 |
820 | ### Why not use `customElements.whenDefined`?
821 |
822 | It is possible to await a custom element definition via
823 | `customElements.whenDefined` which would allow a module to be more tolerant of a
824 | dependency component being defined after it.
825 |
826 | ALTERNATIVE PROPOSAL: Use `customElements.whenDefined` to wait for a component
827 | to be defined somewhere else.
828 |
829 | ```javascript
830 | const el = document.querySelector('my-element');
831 |
832 | // Wait until the element is defined.
833 | customElements.whenDefined('my-element').then(() => {
834 | el.doSomething(); // Definitely defined now.
835 | });
836 | ```
837 |
838 | While `customElements.whenDefined` is a useful primitive, it is insufficient to
839 | meet the goals of this proposal because it:
840 |
841 | 1. relies on _some other module_ in the program to import the definition
842 | of `my-element`, which is not guaranteed to happen synchronously or ever at
843 | all.
844 | 1. "colors" all usage of custom elements to be async which can
845 | block many otherwise-reasonable API contracts.
846 | * For example, both the Lit and HydroActive use cases are synchronous and
847 | would be incompatible with asynchronously waiting for dependencies to be
848 | defined.
849 | 1. requires independent knowledge of the tag name for an element which might
850 | not be known in generic contexts such as libraries or frameworks.
851 | * `MyElement.define();` only requires a reference to the custom element
852 | class, not its tag name.
853 | 1. does not improve tree-shakability of components.
854 |
855 | Beyond those functional points, `customElements.whenDefined` notably does *not*
856 | define a custom element or provide a definition, weakening the relationship
857 | between a custom element and this specific usage. This is very different from
858 | the intent behind On-Demand Definitions which opts to strengthen this
859 | relationship to ensure that a specific, known custom element class is defined
860 | before it is used.
861 |
862 | `customElements.whenDefined` is great for use cases attempting to use a custom
863 | element's definition which may or may not be provided by something else on the
864 | page at any time. That does not describe the problem statement of this proposal
865 | which wants a specific custom element to always be defined at a specific moment
866 | in time. This indicates that `customElements.whenDefined` is the wrong primitive
867 | to solve this particular problem.
868 |
869 | ## Previous considerations
870 |
871 | There is some prior art to be aware of in this space.
872 |
873 | ### `lit-analyzer`
874 |
875 | Lit components expect any of their dependencies to already be defined on the
876 | page prior to being used. This results in a pattern where a Lit element needs to
877 | have a side-effectful import on its dependencies to ensure any custom elements
878 | it needs are already defined.
879 |
880 | ```javascript
881 | import './my-element.js';
882 |
883 | function renderMyElement() {
884 | return html`
885 | Hello, World!
886 | `;
887 | }
888 | ```
889 |
890 | A problem with this developer experience is that it is very easy to forget to
891 | import `my-element.js` or accidentally rely on the side-effect of another file
892 | importing it.
893 |
894 | [`lit-analyzer`](https://www.npmjs.com/package/lit-analyzer) solves this with
895 | its `no-unknown-tag-name` and `no-missing-import` checks which analyze source
896 | code to ensure that any usage of an element in the `html` literal is covered by
897 | a direct import. This validates that every Lit component has a direct dependency
898 | on any elements they require.
899 |
900 | While useful, `lit-analyzer` unfortunately requires the developer to integrate a
901 | distinct service into their toolchain with special knowledge of Lit templates,
902 | which otherwise does not require any such tooling.
903 |
904 | ### HydroActive
905 |
906 | A key goal of [HydroActive](https://github.com/dgp1130/HydroActive/) is to
907 | ensure that custom elements are not accessible to the developer until they have
908 | been defined and hydrated. To that end, HydroActive intentionally hides custom
909 | elements from developers and throws when attempting to access them directly.
910 |
911 | ```javascript
912 | import {component} from 'hydroactive';
913 |
914 | export const MyElement = component('my-element', (host) => {
915 | // Can access native elements like `` directly.
916 | host.query('div').access().element.textContent = 'Hello, World!';
917 |
918 | // ERROR: Custom element `SomeComp` requires an element class.
919 | host.query('some-comp').access();
920 | });
921 | ```
922 |
923 | This throws even when `some-comp` is already defined because it could be defined
924 | coincidentally due the [file ordering problem](#problem-4-file-ordering).
925 |
926 | Instead, HydroActive requires the custom element class to be directly provided
927 | to
928 | [`.access()`](https://github.com/dgp1130/HydroActive/blob/605adcc0bfac70a820c7fdf8fce2a4bfc5c55765/src/dehydrated.ts#L85).
929 |
930 | ```javascript
931 | // Works.
932 | host.query('some-comp').access(SomeComp).element.textContent = 'Hello, World!';
933 | ```
934 |
935 | This ensures that the class declaration of `SomeComp` comes before `MyElement`.
936 | HydroActive intentionally makes this the only easy way of getting access to an
937 | custom element to ensure that this dependency exists.
938 |
939 | However even this approach is forced to assume that a custom element class
940 | declaration is co-located with a top-level `customElement.define` call. This
941 | assumption also prevents tree-shaking of any dependencies. HydroActive
942 | implemented the On-Demand Definitions proposal to mitigate these issues.
943 |
944 | HydroActive's design with respect to file ordering is described more thoroughly
945 | in [this video](https://youtu.be/euFQRqrTSMk?si=i5HKHayt3QvuNytf&t=736), though
946 | it is primarily focused on this problem within the context of hydration.
947 | However, correctly hydrating an element also requires defining it so this is
948 | effectively the same core problem.
949 |
--------------------------------------------------------------------------------