Add information about required polyfills/shims

[alexlafroscia]

I tried the --web-component support just now and recognized the error I faced from other work with customElement that I've done recently. I figured that many people trying it might not be as familiar though, and that it was worth documenting.

The problem is that no browser supports customElement with an ES5 class. Those with native support require a shim to with with Babel (or I guess, Typescript) output and those without native support require a full polyfill. I've mentioned both here.

To make all of this much easier, I'm working on a pull request for for Polyfill.io that can allow developers to include a single URL that automatically pulls in only the required libraries for the browser making the request. However, it's not finished yet; I will update these docs once it does.

https://github.com/Financial-Times/polyfill-service/pull/1101

[pittst3r]

Thanks for the PR! Right now with @glimmer/application-pipeline we automatically don't transpile to ES5 when the @glimmer/web-component package is included in the app's package.json, so I'm not sure we want to tell people to use the native shim (as it won't really do anything). But we are running into an issue with uglify + ES2015+ so the native shim might end up being a part of our story here by default. All that to say, I think we need to figure out this path forward before making browser support recommendations.

[alexlafroscia]

Yeah, so I mentioned this to @tomdale on Twitter and maybe something went wrong with the app that I was demoing this in. He told me the same, that the classes should have been published as ES6 classes, that doesn't seem to be the case. I was getting an error that webComponents.define was receiving an ES5 class, and adding the shim made it all work again. That's why I thought it was something worth documenting, since it wasn't obvious from the existing docs that it should have produced ES6 code.

I'll try out a demo app again and see if I have the same issue; my experience might be a bug elsewhere in the tooling that prevented Typescript from producing ES6 classes the way it's supposed to.

[pittst3r]

You make a good point. We should state how this package affects the build pipeline. Current README is very quick and dirty.

[alexlafroscia]

I can definitely see people getting trolled by the assumption that the code that is produced would be ES5-compliant, since that's how Ember behaves the same way (that certainly trolled me).

[locks]

@robbiepitts update?

[pittst3r]

@locks @alexlafroscia We are now ES5 compatible, so the native shim is not needed. However, if somebody wants web components on a browser that does not have window.customElements they will need the custom-elements polyfill. For context: https://github.com/glimmerjs/glimmer-web-component/pull/13.

@alexlafroscia Could you update your PR to reflect these changes? Essentially:

• ES2015 classes are actually not needed, you just have to construct a special way
• No native-shim needed here
• Can you remove the details on how to include the custom-elements polyfill and just point people to it; I think we will have a better way of including it in the future (i.e. app.import)

[alexlafroscia]

Sure @robbiepitts I'll check that out.

[alexlafroscia]

So I'm trying to get this working locally, so I can update my docs here. However I can't see to get the customElements working at all. Here's what I did so far:

1. Install the Canary version of Ember CLI
2. Run the exact command from the Glimmer website

   ember new display-tile -b @glimmer/blueprint --web-component

3. Add an HTML invocation of the component to src/ui/index.html, by adding the following to the page:

   <display-title></display-title>

However, only one instance of the component is rendered, the one injected into the #app. Furthermore, if you try to look up the component in the customElements registry, it doesn't seem to find it:

^ In there, I'm paused right after the component has been defined, but it returns nothing when looking it up.

[pittst3r]

@alexlafroscia I see a naming inconsistency above. You created the app with the name display-tile but invoked the custom element with the name display-title. Could this be the problem?

[alexlafroscia]

😅 yup, looks like an issue! My bad. I'll try this again tonight.

[pittst3r]

Looks great, thanks @alexlafroscia!