Allow WASM modules to extend the TrailBase admin panel

[zyrakq]

TrailBase WASM modules are currently designed to add endpoints and serve frontend assets for the application itself. This works well for building the app's own user-facing interface, but it leaves a gap: there is no way for a WASM module to surface management or configuration UI inside the TrailBase admin panel.

As a result, if you build a WASM extension that requires configuration — auth providers, feature flags, integrations — you have two bad options: build an entirely separate admin interface outside of TrailBase, or provide no admin UI at all. Neither is acceptable for extensions that are meant to be self-contained.

What's needed:

• A way for operators to see which WASM modules are currently loaded in the admin dashboard
• An opt-in mechanism for modules to declare their identity (display name, icon, description) so they're recognizable in that list
• A way for a module to expose its own management/settings page that renders inside the TrailBase admin UI, without requiring changes to TrailBase core for each new module

This would make WASM a viable model for building first-class admin extensions, not just application-layer plugins.

[zyrakq]

Related issues: #165

PR: #253

The PR is just my take on how this could work — not a finished solution. Happy to discuss the approach.

[ignatz]

The PR is just my take on how this could work — not a finished solution. Happy to discuss the approach.

Definitely thanks for pushing this up on the priority list. This is something I've toyed with in the back of my head for a while. We should definitely discuss a bit more what the end-state should be also since I haven't convinced myself yet what it should look like.

Let me address the elephant in the room before sweeping it under the carpet: we could make the whole admin UI its own WASM module similar to the auth-ui. It would then be easier to fork and modify. Clearly this doesn't have the compositional properties you're after, i.e. plugins from various other wasm components, but may be something we may want to keep open as an option besides plugins in the future.

Now to your proposal (I have only skimmed it, a few points):

• I like declarative, which some parts are. I don't love the probing at /_/wasm/{component_name}/manifest, when https://github.com/trailbaseio/trailbase/blob/main/guests/typescript/wit/init.wit#L4 would be more consistent with how we already register http endpoints, sqlite functions, ...
• I like that an admin API deals as the mediator between the purely client-side admin app and the components.
• I'd love to hear why you decide to inject the HTML in the admin client-app instead of e.g. an iframe?

[zyrakq]

Thanks for the detailed reply! Happy to dig into all of these.

Let me address the elephant in the room before sweeping it under the carpet: we could make the whole admin UI its own WASM module similar to the auth-ui. It would then be easier to fork and modify. Clearly this doesn't have the compositional properties you're after, i.e. plugins from various other wasm components, but may be something we may want to keep open as an option besides plugins in the future.

I'd love to see that direction kept open too, but my hunch is most developers won't want to fork the entire admin just to slot in their extension. You'd get maximum flexibility for the few who need it, but raise the barrier for everyone else.

What this PR aims for is a simpler, predictable contract: each module can claim its own page under /wasm-modules, and that covers the common case where you don't need to reshape the admin — you just need a place for your config UI. Later on it'd be worth looking at injecting into arbitrary sections without rewriting the admin, but for the baseline case a dedicated modules page felt like the right granularity.

Taking the modular idea further: I'd love to see the auth surface itself — the admin sections for authentication settings and email templates — eventually live in their own WASM module rather than being baked into the admin core. Right now only a handful of endpoints and UI bits are extracted. Pulling the whole auth/settings UI into a module would make the admin leaner and make auth genuinely pluggable. This PR is a small step toward that: if settings pages can come from modules, the auth settings page could too. That said, if the admin itself becomes a module, it shouldn't be a monolith either — the auth section, email templates, and similar concerns could each be submodules. Web components feel like a natural fit there: each submodule ships its own custom elements, and the admin module just composes them.

I like declarative, which some parts are. I don't love the probing at /_/wasm/{component_name}/manifest, when https://github.com/trailbaseio/trailbase/blob/main/guests/typescript/wit/init.wit#L4 would be more consistent with how we already register http endpoints, sqlite functions, ...

Started down the WIT path — adding something like init-manifest to the existing init-endpoint. The problem is that WIT interfaces are a hard contract at instantiation time: adding a new function to an existing interface means the host's instantiate fails on any component that doesn't export it. Every existing module stops loading.

The alternatives were a separate versioned world with an optional-instantiation fallback (the runtime doesn't support that today), or breaking the ABI and forcing everyone to recompile. The HTTP probing sidesteps all of it — it goes through wasi:http/incoming-handler, which every component already exports, and a 404 or parse failure just means "no manifest." It looks ad hoc because it's deliberately picking the backwards-compatible path. Definitely open to revisiting if there's a cleaner way to do optional WIT exports.

I'd love to hear why you decide to inject the HTML in the admin client-app instead of e.g. an iframe?

A few reasons I went with injection:

• iframes don't auto-size to content, so you get either a fixed height or a nested scrollbar — neither feels right in a settings panel
• injection leaves the choice to the module author. Want isolation? Wrap in a Shadow DOM — it still inherits CSS variables like --primary, so theming keeps working. Want to lean on the admin's styles? Just don't wrap it. And if you specifically want an iframe, nothing stops you from putting one in your own HTML. With an iframe as the base approach though, isolation is forced on everyone with no opt-out.

[zyrakq]

One thing I want to expand on — the way I think about modules is a bit different from "UI module + core backend." To me the interesting model is each WASM component being a full vertical slice: its own endpoints and its own UI, self-contained. More microfrontend + microservice than just a detached frontend shell.

The iframe point actually ties into this directly. The reason the microfrontend community moved away from iframes toward web components + Shadow DOM wasn't arbitrary — it's because you need composability, not just isolation. Web components let you define custom elements that compose naturally inside any host page, inherit design tokens through CSS variables, and communicate through standard DOM events. iframes are islands; web components are building blocks.

And if the style leakage from innerHTML injection is a concern, the fix is straightforward: just require the config_path response to register a Custom Element. The admin page mounts it by tag name, and Shadow DOM encapsulation kicks in automatically — no extra wrapping needed, and every module gets isolation by default.

On auth specifically: I get that the auth-ui module is intentionally UI-only. But I'd push back a little on keeping the auth backend in core long-term. Even if a given TrailBase user doesn't need it, shipping one auth implementation as a non-negotiable part of core is a design commitment that gets harder to undo. Auth isn't a settled space — OAuth/OIDC is dominant today, but Nostr-based auth, WebLN, Web3 wallet signing are all real and developing. Embedding a single answer in core means anyone who wants something different has to work around it rather than replace it. A pluggable auth module — backend included — seems like it'd age better and make TrailBase more genuinely composable.

[zyrakq]

A small demonstration of the modifications on the wcauth module:

[ignatz]

Thank you for your thoughtful replies and sorry for the latency (was out for a few days).

A small demonstration of the modifications on the wcauth module:

Something to look at is always exciting. Awesome!

On auth specifically: I get that the auth-ui module is intentionally UI-only. But I'd push back a little on keeping the auth backend in core long-term. Even if a given TrailBase user doesn't need it, shipping one auth implementation as a non-negotiable part of core is a design commitment that gets harder to undo. Auth isn't a settled space — OAuth/OIDC is dominant today, but Nostr-based auth, WebLN, Web3 wallet signing are all real and developing. Embedding a single answer in core means anyone who wants something different has to work around it rather than replace it. A pluggable auth module — backend included — seems like it'd age better and make TrailBase more genuinely composable.

Probably, yes. In practice it will be some way. There's a bit of a chicken and egg problem: you need to have a rich ecosystem and all the necessary infrastructure before it makes sense to strip out. Why stop at auth? :) - Ultimately, if everything becomes a WASM component and the core does nothing anymore, is TrailBase "just" a WASM runtime? - Maybe 🤷‍♀️. Note that there are other projects, e.g. https://spinframework.dev/, that are following the "empty-shell" approach. At least my initial drive was to offer something closer to Firebase, Supabase, ... that is a bit more turn-key, works best in new projects and only many but not all... That said, if one day we wake up with a marketplace and a handful of high-quality auth components in it, removing the built-in one would feel very natural.

And if the style leakage from innerHTML injection is a concern, the fix is straightforward: just require the config_path response to register a Custom Element. The admin page mounts it by tag name, and Shadow DOM encapsulation kicks in automatically — no extra wrapping needed, and every module gets isolation by default.

Styling is certainly one aspect of the compositional model. I was wondering if there are other isolation concerns from an access/leakage point-of-view. Ultimately, as long as dashboard pages are tied to WASM components, they'll always require deep trust by the installer given the capabilities they already have (e.g. access the entire DB). In other words, iframe's wouldn't provide any protection for a lot of sensitive data. It's probably just coping on my end. That said, in practice I would always start tight and loosen when necessary. Taking away things later is always the harder route 🤷‍♀️

Started down the WIT path — adding something like init-manifest to the existing init-endpoint. The problem is that WIT interfaces are a hard contract at instantiation time: adding a new function to an existing interface means the host's instantiate fails on any component that doesn't export it. Every existing module stops loading.

Presumably we'd only add it once and then hardly ever touch it? Even then, WIT supports versioning to support forward-backwards compatible rollouts (to some extend, there are glaring oversights). I'm wondering if there's anything in particular you have in mind. I defensively feel that whatever we settle on should be applied consistently, rather than exposing 70% of a component's capability one way and then 30% another 🙃

[zyrakq]

Thanks for the thoughtful reply, and no worries about the delay!

Note that there are other projects, e.g. https://spinframework.dev/, that are following the "empty-shell" approach.

Appreciate the pointer, hadn't looked at it that closely before. Like the serverless idea in principle, but my gut feeling is that going full "empty-shell" introduces a lot of small operational complexity that's a rough fit for open-source or personal projects — too many moving pieces for what's usually a one-person or small-team setup. Honestly this is part of why I picked TrailBase in the first place: you can start writing everything directly against axum, and only pull things out into modules once there's an actual reason to reuse or isolate them. Glad you brought it up though, it clarified for me why that tradeoff matters.

Why stop at auth? :) — if everything becomes a WASM component and the core does nothing anymore, is TrailBase "just" a WASM runtime?

Fair, and I get it now. Overcomplicating the entry point is a real cost, and honestly I like that TrailBase ships with a lot of functionality out of the box rather than being a blank slate. That also clicked something for me about auth-ui — it's scoped to just the interface pieces so people using TrailBase as a ready container/CLI tool can swap out pages they don't like without losing any of the underlying functionality.

That said, I think there's a middle ground worth considering: treating auth as its own standalone project, the same way TrailBase itself can be embedded as a framework crate. Something like Dex, but positioned the way TrailBase is — a project that can either stand alone or be pulled in and become part of TrailBase as a crate-framework. You've actually already moved partway there by splitting it into separate crate(s). The piece I'd push for first is exposing it as a Cargo feature, so a developer can turn the built-in one off and drop in their own implementation without forking anything.

Styling is certainly one aspect of the compositional model. I was wondering if there are other isolation concerns from an access/leakage point-of-view.

Also pushed a commit switching the settings-page mount from raw innerHTML to injectFragment backed by a web component with Shadow DOM. Stricter version — styles don't leak either direction now.

Presumably we'd only add it once and then hardly ever touch it? [...] I defensively feel that whatever we settle on should be applied consistently.

Wanted to give more context on the reasoning behind the manifest route, and then walk through what I changed.

Why HTTP originally: init-endpoint is strictly instantiated — wasmtime checks the real export list, @since is documentation only, it doesn't relax that. Any function added there breaks every already-compiled component that doesn't export it. The manifest isn't something every component has, so putting it in init-endpoint felt wrong from day one. Serving it over HTTP (registered like any other route via init-http-handlers) sidestepped that entirely — missing manifest is just a 404, nothing at instantiation time cares either way.

What I changed: since consistency with the rest of the WIT-driven capabilities matters, moved the manifest off HTTP and onto a new optional-WIT mechanism:

• init-endpoint stays exactly as is, strict instantiation unchanged.
• Added a standalone manifest-endpoint interface, deliberately left out of world interfaces exports — never part of the strict contract.
• Host does the normal strict instantiate first, then separately probes for manifest-endpoint via the raw wasmtime::component::Instance API (get_export_index + typed func lookup) — bypasses bindgen! for that probe entirely. Present → call it. Absent → None + debug log. Functionally the same guarantee as the HTTP 404 had, just through WIT.
• Guest side: separate OptionalManifest trait + export_optional! macro, independent of the existing Guest trait. Components that don't implement it are unaffected — checked against auth_ui, loads with zero errors, zero changes.
• Manifest is just the first thing exercising this, the probe mechanism itself is meant to be reusable for whatever optional capability comes next.

[ignatz]

Thanks for your thoughtful reply and bearing with me 🙏

What I changed: since consistency with the rest of the WIT-driven capabilities matters, moved the manifest off HTTP and onto a new optional-WIT mechanism:

The change has certainly become more involved and I'll need to give it a thorough look. I'll admit, I'm not a 100% sure what the implications are of adding new worlds and interfaces to a package w/o bumping the package version 🤷‍♀️

Why HTTP originally: init-endpoint is strictly instantiated — wasmtime checks the real export list, @SInCE is documentation only, it doesn't relax that. Any function added there breaks every already-compiled component that doesn't export it. The manifest isn't something every component has, so putting it in init-endpoint felt wrong from day one. Serving it over HTTP (registered like any other route via init-http-handlers) sidestepped that entirely — missing manifest is just a 404, nothing at instantiation time cares either way.

You're right, I keep confusing myself. Adding new imports (i.e. host interfaces) sub-typing works but adding new exports (component interfaces) everything breaks. There's some talk about allowing optional interfaces and/or versioning on records/enums but as it stands WIT is pretty limited and things have been moving at a steady pace but the ecosystem is frustratingly fragmented, e.g. wasmtime now supports wasip3 but JS components don't... (I digress).

As for backwards compatibility for old components, I'm of two minds. One side vicariously agrees with you that it's a good property especially long-term if/when there could be an ecosystem letting users mix 1st and 3rd party components. At the same time, my other sides cautions that we're early in the lifecycle and working around limitations of WIT by introducing inconsistencies. FWIW, also today not all components export HTTP handlers and cron jobs. It's currently addressed by providing empty default implementations, the same approach could work here given users re-build their components (which is what you're trying to avoid).

At the end of the day, I care more about consistency than preserving what's already there. I'm wondering if we wouldn't be better off to change all the init-endpoints to just return a protobuf (or similar like avro) manifest which supports better versioning. We'd still fore component rebuilds at least one more time but hopefully going forwarincompleted less often 🤷‍♀️. Sadly, it has been a pain and will continue to be a pain if we rely on WIT as is right now :(.

That said, I think there's a middle ground worth considering: treating auth as its own standalone project, the same way TrailBase itself can be embedded as a framework crate. Something like Dex, but positioned the way TrailBase is — a project that can either stand alone or be pulled in and become part of TrailBase as a crate-framework. You've actually already moved partway there by splitting it into separate crate(s). The piece I'd push for first is exposing it as a Cargo feature, so a developer can turn the built-in one off and drop in their own implementation without forking anything.

I think we're mixing two levels of composition: WASM components and framework use. I would expect most folks to pick one or the other. It's a bit of a flex to extend your own binary and then pull in more custom functionality using wasm components (maybe I'm wrong and everyone wants the auth-ui 🤷‍♀️).

To be clear, I'm not opposed and I absolutely want folks to be able to run their own auth, whether thats a separate binary, a custom trail binary or a WASM component. I'd certainly be down to add a switch to turn off the built-in auth routes independent of pulling the APIs into a WASM component. When it comes to pulling out the auth APIs into a WASM component 🤷‍♀️ . Unless we pull everything out it feels a bit arbitrary. I wouldn't expect much benefits in practical terms: performance would be marginally worse, binary size would be marginally better... all in all a wash. With the built-in auth disabled, one should be able to write their own component or binary with their own auth today.

To not stall you any longer, I'd be happy to change the init-endpoint to use some more flexible opaque serialization format. Curious to hear what you think.

[zyrakq]

I'd be happy to change the init-endpoint to use some more flexible opaque serialization format.

Understood — rebuilding old components isn't a concern for you right now, so I'll switch to init-manifest with a default empty implementation soon. Might look at protobuf/avro later too, but that's clearly outside this PR's scope.

I think we're mixing two levels of composition: WASM components and framework use.

Think that comment threw you off — by that point I was no longer proposing pulling auth into a WASM component, I'd already moved past that idea and was talking about something else. The Dex comparison was about crate-level composition: a standalone project that can also be pulled in as a framework dependency, same as TrailBase itself one level up.

To be clear, stepping back from the Dex/standalone-project angle and the feature flag — I did raise those, but none of it belongs in this PR. It was a tangent, and thinking it over I don't want it to distract from the manifest/WIT work that's actually on the table here.

[zyrakq]

Regarding the config topic raised in #257 (and it's relevant here too, since it overlaps) — wanted to chime in.

One way this could work: let a WASM module declare its config structure (e.g. via textproto), and once the module's registered, that becomes part of TB's own config — stored under its own subfolder in traildepot. That keeps each module's config isolated and versioned without core needing to know the schema upfront.

Ran into this myself, actually before I saw the #257 thread — I started with the settings-page mechanism first, so the question of where a module's config lives came up early, and I just parked it. For now I'm working around it with a migration that creates a table for the module's config — the module's page explicitly tells you to drop that migration into migrations for it to work. Not clean, but the settings-page piece was the priority, so I left the proper config story for later.

[ignatz]

One way this could work: let a WASM module declare its config structure (e.g. via textproto), and once the module's registered, that becomes part of TB's own config — stored under its own subfolder in traildepot. That keeps each module's config isolated and versioned without core needing to know the schema upfront.

Doesn't seem unreasonable. It's common for other sandboxed environments to handle settings (e.g. shared preferences) separately from FS access. Otherwise, with FS access a component could also handle it itself.

Ran into this myself, actually before I saw the #257 thread — I started with the settings-page mechanism first, so the question of where a module's config lives came up early, and I just parked it. For now I'm working around it with a migration that creates a table for the module's config — the module's page explicitly tells you to drop that migration into migrations for it to work. Not clean, but the settings-page piece was the priority, so I left the proper config story for later.

FWIW, you're calling DB storage a work-around but it may be the future. For a more distributed, e.g. edge replicas, HA, ... , it would be a pain to synchronize config files if the DB is already shared. That said, even if this was the eventual direction it doesn't dictate the above conversation: distribution of responsibilities. Even in such a case you may want to defer settings (a la shared preferences) to the host 👍

[ignatz]

Understood — rebuilding old components isn't a concern for you right now, so I'll switch to init-manifest with a default empty implementation soon. Might look at protobuf/avro later too, but that's clearly outside this PR's scope.

To be clear, I'm happy to upfront the work, i.e. could get it done in one or two days if you'd like to base yours on top. I somewhat wishful intent would be to create less churn going forward. That said, I also wouldn't want to hold you back based on good intents.

[zyrakq]

Sounds good, go for it 👍