docs: warn that hydration plugins are required for interactivity#301
Draft
janechu wants to merge 1 commit into
Draft
docs: warn that hydration plugins are required for interactivity#301janechu wants to merge 1 commit into
janechu wants to merge 1 commit into
Conversation
A handler constructed without a plugin renders HTML but does not inject the hydration markers (data-fe, <!--fe:b-->, etc.) that client runtimes look for. The result is a silent failure: the page looks correct after SSR, but the FAST / WebUI client never wires up event handlers or signal bindings. Add a callout to the plugins concept page so this trade-off is visible at the point where embedders pick between WebUIHandler::new() and with_plugin(...). No code changes.
mohamedmansour
requested changes
May 18, 2026
Contributor
mohamedmansour
left a comment
There was a problem hiding this comment.
This is not true, you can still use HTMLElement and add your own interactivity.
WebUI only supplies the SSR and you can use any client side framework or even no framework for interactivity, the "plugins" are only there if you need special output. Like f-template or comments for helping hydration.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds a
::: warningcallout to the plugins concept page explaining that a handler constructed without a plugin emits no hydration markers, which silently breaks client-side interactivity.Problem
A handler constructed via
WebUIHandler::new()(Rust) or with nopluginoption (Node.js) emits the rendered HTML but does not inject the hydration markers (data-fe,<!--fe:b-->, etc.) that client runtimes look for. The result is a silent failure mode that is genuinely hard to debug:curloutput, ships to the browser.enableHydration()is called on a page that has no hydration markers; it finds nothing to bind to, returns successfully, and the page is interactive in the sense that custom elements are upgraded but none of the FAST bindings, event handlers, or signal subscriptions wire up.There is no error, no warning in the console, no failed assertion. The page just doesn't come alive.
This trade-off is real and intentional -
WebUIHandler::new()is the right choice for static SSR (sitemaps, RSS index pages, content that ships HTML and never hydrates). It is the wrong choice for any component that wants client-side interactivity. The docs do not currently call this out.Change
One
::: warning Hydration plugin is required for interactivityblock added todocs/guide/concepts/plugins/index.md, placed right before the cross-language "Using Plugins with Handlers" code tabs so the reader sees the warning before they copy the example. The warning names the plugin types per-framework (FastV3HydrationPlugin,WebUIHydrationPlugin) and explicitly states when the plainnew()form is appropriate (static SSR only).No code changes.
Companion PRs
microsoft-webuiso the recommended constructionWebUIHandler::with_plugin(|| Box::new(FastV3HydrationPlugin::new()))works with a single dependency.