Skip to content

docs: warn that hydration plugins are required for interactivity#301

Draft
janechu wants to merge 1 commit into
mainfrom
users/janechu/document-fast-v3-hydration-required
Draft

docs: warn that hydration plugins are required for interactivity#301
janechu wants to merge 1 commit into
mainfrom
users/janechu/document-fast-v3-hydration-required

Conversation

@janechu
Copy link
Copy Markdown
Contributor

@janechu janechu commented May 16, 2026

Summary

Adds a ::: warning callout 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 no plugin option (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:

  • Server-side: HTML renders fine, looks correct in curl output, ships to the browser.
  • Client-side: 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 interactivity block added to docs/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 plain new() form is appropriate (static SSR only).

No code changes.

Companion PRs

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.
Copy link
Copy Markdown
Contributor

@mohamedmansour mohamedmansour left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants