How to make web pages extensible by add-ons?

[RumovZ]

In the past, there have been different approaches. For both Anki core and add-on development, it would be beneficial to have a consistent approach going forward.
@glutanimate, @abdnh, and any other contributors or add-on authors, your input would be appreciated!

So far we have come up with three different strategies.

1. Svelte components

Add-ons build their own components, while being able to reuse any Anki code they like.

Example: https://github.com/hgiesel/anki_new_format_pack

2. Raw HTML and JS

Add-ons manipulate the DOM directly, with hardly any support from Anki.

Example: https://github.com/ankitects/anki-addons/tree/main/demos/deckoptions_raw_html (not functional)

3. Parameterisation

Anki exposes a strict feature set add-ons can pick from.

Example: #3145 / ankitects/anki-addons#21

Comparison

As a discussion starter, I've tried to summarise the arguments so far. ✔️ means pro and ❌ con. Blank is somewhere in between.
Happy to discuss these or extend the list.

	Svelte components	Raw HTML & JS	Parameterisation
Consistent UX	✔️	❌	✔️
Maintenance cost (Anki)	❌	✔️	❌
Development cost (add-ons)		❌	✔️
Robustness to Anki changes	❌		✔️
Expressiveness	✔️	✔️	❌

[dae]

I've added an example for number 1, though judging by reviews on https://ankiweb.net/shared/info/1187194862, it's already broken as well.

[abdnh]

The parameterization approach looks simpler to use (no Svelte setup required?) but supporting UI extensions is probably more work with this approach.

I imagine the Svelte components approach is more suitable for certain pages like the graphs page. I like its flexibility and would love to use it in any Svelte page.

[dae]

There are actually 2 ways we could approach number 1:

a) the current way, where add-ons can make runtime use of the existing components in Anki. Changes in things like props passed to a component would break the add-on
b) by allowing add-on authors to import Anki components at bundle time. This would mean they'd ship with a snapshot of the components at build time, and API changes in new Anki versions should not break their code.

The second approach could potentially be combined with approach 2: use raw HTML/JS if you wish, or use your own Svelte code which happens to import Anki components.

It's not without its own complexities and downsides: we'd need to make it easy to include the components, such as by publishing an NPM library. And our components reference other things like the protobuf TS code, our fluent translations, etc - do we bundle those too? Do we stub them out and still use them dynamically? And how do we pass reactive state into the raw HTML/JS?

But there would be some positives: it largely decouples the add-ons from Anki, making them less likely to break when we refactor, and that breakage would tend to happen when they build their add-on, not when it's run.

[RumovZ]

I was hoping someone with more add-on experience would further the discussion instead. But I'll do my best.

The NPM library seems like the most robust and versatile approach, provided we can overcome the bundling difficulties and you're willing to carry the maintenance burden.

Do we stub them out and still use them dynamically?

As for the protobuf code, is there a difference between bundling the generated code or stubbing it out? I mean, it would break anyway when Anki's protobuf code changes, so I would just do what's simpler to bundle.

As for the fluent translations, bundling them seems preferrable. Add-ons would miss out on translations added later on, but more importantly, there would be no breakages when Anki drops unused strings.
If package size is a concern, maybe translations could be made optional dependencies.

And how do we pass reactive state into the raw HTML/JS?

Isn't it the same as before? I.e. they require a package and subscribe to its stores.

[dae]

As for the fluent translations, bundling them seems preferrable

That seems like a fair bit of extra work. As you know, we currently embed the translations in the Rust shared library. To bundle them in an npm library, we'd need to ship them separately, and provide a way for the frontend to load them. And different add-ons could be loading different versions. We tend not to delete existing translations quickly when making changes, so I'm not sure it's worth all the extra work to freeze them?

Isn't it the same as before? I.e. they require a package and subscribe to its stores.

With the stores hidden behind a promise, it makes the add-on API a bit more cumbersome, as add-ons wouldn't be able to immediately refer to a $store - so in the case where they're using Svelte and not raw HTML, they'd need to either have derived values that resolve after the promise, or they'd need to use {#await ...} or similar. Not a showstopper though, and it does mean the stores don't need to be nullable.

[popyoung]

Maybe I found a resolution for Raw HTML and JS. Just unpack the code from the function 'setup'.
https://forums.ankiweb.net/t/what-happened-to-my-addon/44965

Relevant pull request: ankitects/anki-addons#22

[RumovZ]

I think I need some code to look at at this point. You seem to favour the approach with bundled Svelte components, @dae. Should I try to build an example add-on?