Addon adoption plan

[simonihmig]

I wonder when and how addons should start adopting Glint, and what still needs to be done to do so?

The Readme still mentions it's too early for addons to adopt, but what is actually still too unstable? Re-exports are gone already, and other things like the template registry are going to stay as they are, aren't they?

I found out about glint-template-types too late (should have RTFM), but even with that a good amount of addons we use aren't covered. For those that I maintain myself, I would rather spend the time on making them come with their own types, rather than having to maintain un-synced ambient declarations. Or having those typed as any-like, which I currently do, but that obviously defies the purpose...

I guess addons can already use Glint internally for their own type safety without problems, right? So the question is more how to make them correctly publish their types, and how the app will consume them. I guess (without strict mode) the app would need to explicitly import them from somewhere, right?

If you don't have strong arguments against it, I'd be willing to experiment with some addon, to see how it goes. As long as it does not cause issues for non-Glint consumers, I would see Glint-support as an experimental feature for now, so wouldn't mind occasional breaking changes or rough edges...

[dfreeman]

Re-exports are gone already

Re-exports are no longer mandatory, but we're still in the process of actually getting rid of them and updating the documentation—I'm putting together a PR for part of that work right now 🙂

To your point, that was a huge blocker to addon adoption that is almost behind us, which makes this a great time to reassess the story for addons that wish to support Glint.

The simplest answer is that addons "just" need to start declaring Signature types using the most recent @glimmer/component, @types/ember__component and ember-modifier releases.

So the question is more how to make them correctly publish their types, and how the app will consume them.

That's right; the work that remains right now is largely around establishing a good set of conventions for addon authors and their consumers to follow for how to work with Glint-enabled addons. Beyond making proper use of signatures, the two main questions I see are:

1. How do addon authors deal with publishing signatures that involve types like ComponentLike?
2. Who is responsible for adding an addon's template entities to the registry?

For (1), the current thinking is to have addon authors declare a dependency on @glint/template (a types-only package with no runtime content) but that does place a burden on maintainers as we move through potentially-breaking releases there on the way to 1.0. It's also extra "weight" in the form of an additional dependency for the addon, even if it has no impact on the production artifacts.

For (2), I think there are arguments to be made either way, with tradeoffs in ergonomics and flexibility depending on whether the addon itself or the app is responsible for putting additional entries in the template registry.

If you don't have strong arguments against it, I'd be willing to experiment with some addon, to see how it goes. As long as it does not cause issues for non-Glint consumers, I would see Glint-support as an experimental feature for now, so wouldn't mind occasional breaking changes or rough edges...

I think that's a great idea! I'd love to hear about any other issues you come across that we haven't considered. Thank you for being willing to experiment 🙂

[simonihmig]

Who is responsible for adding an addon's template entities to the registry?

On the one hand, giving the app ownership of the template registry seems reasonable, as that's how things effectively work today, at least without strict mode and v1 addons with their /addon and /app trees: they might push code into the app namespace, but at the same time the app will always be able to override anything the addon exposes. So it should have the final word...

On the other hand, this (overriding) is certainly the exception to the rule, like happening in <1% of cases probably? So forcing users to import and add things to the registry seems like a bad DX in the general case. Tbh I was puzzled a bit when I read this is what this glint-template-typesimposes on users. Just imagine doing this for a larger UI kit addon (bootstrap, material etc.) or ember-{math,truth,composable}-helpers with dozens of entries.

But maybe we can allow both?

On to my experiment first...

I added Glint to a TS-based addon here: simonihmig/responsive-image#400 in the "usual" way, i.e. the template registry stuff was added in each module of a component or helper.

The next step was to figure out how an app would be able to consume this. Interestingly the VSCode plugin seems to recognize this automatically: without any manual import it would show the correct component type in an app template. However that is (expectedly/correctly!?) not true when running glint CLI. I assume it needs to see an import of a module that features the template registry declaration to incorporate that, like any other tool that relies on static analysis of ES modules and which has no knowledge of the special build-time Emberisms, right?

So in simonihmig/responsive-image#401 I added a glint.ts file which imports all the Glint-enabled modules (of the addon). Which I then imported from within the app's types/glint.d.ts, where I also had the other mandatory glint imports:

import '@glint/environment-ember-loose';
import '@glint/environment-ember-loose/native-integration';
import 'ember-responsive-image/glint';

This now made also Glint CLI happy. So the second use case of easily adding all the addon provided template registry entries seems to be covered, requiring just a single import from the app.

Now back to making the app own the addon's template registry entries. The idea here is to not import that glint.ts file, and rather import the actual component and manually add it to the registry, like this:

import type ResponsiveImage from 'ember-responsive-image/components/responsive-image';

declare module '@glint/environment-ember-loose/registry' {
  export default interface Registry {
    ResponsiveImage: typeof ResponsiveImage;
  }
}

On first glance this worked. However the entry above did not have any actual effect, as the template registry declaration of the component module (ember-responsive-image/components/responsive-image) "won", and the one in the app above seems to have no effect. I tried to confirm this by doing something silly like this:

import type ResponsiveImage from 'ember-responsive-image/components/responsive-image';

declare module '@glint/environment-ember-loose/registry' {
  export default interface Registry {
    ResponsiveImage: string; // just to trigger a type error
  }
}

This actually still works, Glint passes, the type of <ResponsiveImage/> in a template was the one from the addon's module, so that intentionally wrong string type did not have any effect. Which means in case the app wanted to override the component with a different one (maybe even one with an incompatible shape), this wouldn't have worked.

Tbh I was quite puzzled by that behavior, as I would have expected the "later" declaration to win. And TS to actually emit an error due to those incompatible shapes. But this was not the case! 🤔

So what did work to enable that use case was to move the template registry stuff from the actual component/helper modules to our glint.ts file. You can see that happening in the diff of that second PR. So the app user will either import that file, have the registry entries added automatically, and not need/be able to add or override the addon provided types. Or they can choose to not import that file, but rather import the components/helpers (types) individually (which now contain no registry entries), and add their types to the registry themselves (or those of their own overridden components).

Does that make sense so far? And is this dual mode approach something we should try to establish as an opinionated pattern for addons to adopt? (still room for bikeshedding the details)

[dfreeman]

Thank you for exploring and writing all this up, @simonihmig!

Tbh I was quite puzzled by that behavior, as I would have expected the "later" declaration to win. And TS to actually emit an error due to those incompatible shapes. But this was not the case!

That's surprising to me, too—I would definitely have expected an error there! Is there any chance your app had skipLibCheck enabled in its tsconfig? What that flag means in practice is "don't emit errors from .d.ts files", which can often mask problems like that.

So the app user will either import that file, have the registry entries added automatically, and not need/be able to add or override the addon provided types. Or they can choose to not import that file, but rather import the components/helpers (types) individually (which now contain no registry entries), and add their types to the registry themselves (or those of their own overridden components).

I like this approach a lot 👍
I think it strikes a good balance of requiring minimal manual setup for typical users, while leaving the flexibility for folks to override if they absolutely need to.

@chriskrycho @jamescdavis seem reasonable to you?

[jamescdavis]

Yes, this seems quite reasonable. It makes the common use-case easy, but leaves room for customization when needed. I like it.

[chriskrycho]

Fairly standard “progressive disclosure of complexity” model, so I’m 👍🏼. My only note here is: we definitely need to document this pattern for the medium-term, but/and we should also take the place where we document it as a place to call out the advantage of switching to first-class component templates, where you get it “for free” with no registry shenanigans.

[simonihmig]

Thanks for the positive feedback!

I took some hours of my "OSS friday" to work on the documentation, please have a look: #313 😀

[simonihmig]

Oh, and I also published my addon experiments above: https://github.com/kaliber5/ember-responsive-image/releases/tag/v3.4.0

Probably the first addon shipping Glint types!? 😀 🎉

[simonihmig]

Is there any chance your app had skipLibCheck enabled in its tsconfig?

Oh yes, indeed, this is the case! Nice catch!