Runtime agnostic web components

[matthewp]

I'm spinning this off from #7. 1 of the underlying goals in that issue is:

• Prevent running server-only code in the client.

This issue is for discussing ideas on how to write web components in such a way that they can be run in any JS environment without throwing. Environments might include: The web, web workers, Node.js, Deno, Cloudflare, among others.

Custom elements have at least 2 dependencies that are web (main thread) specific APIs, HTMLElement and customElements. A typical custom element is written like this:

class MyElement extends HTMLElement {

}

customElements.define('my-element', HTMLElement);

While libraries often provide their own base class and some might also register the element for you, it doesn't change the fact that these APIs are dependencies in an element's graph.

I would add to the list of goals the following:

• Elements should not rely on a shimmed environment, ie no patching globalThis.

Note that this issue does not try to address how much of HTMLElement is needed, as that will vary depending on the element. Some elements might need setAttribute, for example, while others might not need any methods of HTMLElement at all.

Below I'm going to post some ideas on how to structure custom element code to address this problem. I encourage others to provide their ideas as there are multiple ways to tackle it.

[matthewp]

Mixin pattern

The mixin pattern is when your module exports a function that takes a base class to extend. This prevents the dependency on HTMLElement.

export default function(BaseElement) {
  return class extends BaseElement { /* ... */ }
}

We could use this similar pattern while still allowing the element to do its own registration.

export default function(BaseElement, customElements) {
  customElements.define('my-element', class extends BaseElement {

  });
}

In the client you would have a simple wrapper:

my-element.client.js

import register from './my-element.js';

register(HTMLElement, customElements);

And on the server you would provide implementations of these:

import register from './my-element.js';

class HTMLElement {
  // This can be as complex or as simple as the element needs.
}

class CustomElementsRegistry extends Map {
  define(...args) {
    this.set(...args);
  }
}

const registry = new CustomElementsRegistry();

register(HTMLElement, registry);

[fgirardey]

It sounds interesting, but is this really runtime agnostic? I mean for the registration part, yes it does, but it can't prevent developers to pull browser APIs in their web components, so we'll still have to deal with the problem.

I might be missing something (maybe the whole point of the proposal here, please don't be offended, I am not very experienced and not English fluent) but if web components still need to access to global objects like window or document then injecting or providing global objects will still be necessary and I think that the Realms API proposal will make it easier to execute a web component in a DOM like context.

To conclude my question is: is it really necessary to require that web components authors should split the implementation and the registration of web components if it only solves the registration issue?

[matthewp]

@fgirardey This seeks to create a convention for passing dependencies through a registration function, so you could pass any dependency that the element has, not just the HTMLElement and customElements objects. An element that is conforming to this convention is doing so on purpose, so we should assume that they will not use browser-specific globals but rather use passed in values.

Would an object as the first parameter be better? That way the provider can pass in as many dependencies as the element has, and then the element can destruct:

export default function({ BaseElement, customElements }) {
  customElements.define('my-element', class extends BaseElement {

  });
}

---

Also, #18 was created as a way to shim the global environment without setting browser globals on it, so it's an idea in a similar vein to what you are suggesting. Happy to discuss your idea in that issue.

[fgirardey]

Thank you @matthewp, I have no particular suggestions, I like this injection approach, as a software developer, is perfectly understandable and actually desirable.

But I have concerns about the feasability to make every developers to do so. Obviously this good practice will not be applied by every developer and we'll still have to deal with custom elements that directly use globals.

I am probably too pessimistic but I think that it should be the responsibility of the container to deal with the global issues rather than the contained element.

I've read #18 but I don't see how it will help because the existing custom elements will need to opt-in and use those well-known symbols.

[matthewp]

Thanks @fgirardey, I'm going to answer your feedback on #18 in that issue.

---

As for the feasibility of this idea, I agree with you that it's unlikely to sway enough people to adopt this pattern, which is why I started #18 as an alternative. It's worth keeping open a little while longer just in the off-chance that the community would be interested in adopting the idea though.