docs: add embedded fragment rendering recipe page#299
Conversation
effa56b to
dc1197f
Compare
WebUI already supports rendering a single named fragment from a host that isn't itself a WebUI app via the `entry` option on `render` / `renderStream` (Node) and `RenderOptions::new(entry, request_path)` + a custom `ResponseWriter` (Rust). The docs don't currently call this out, so an adopter has to infer it from the full-page recipes and the `RenderOptions` type. This PR adds `docs/guide/integrations/fragments.md`, a focused recipe page covering: - When to embed a fragment vs adopt a full-page integration. - Node recipe with both `renderStream` and `render`. - Rust recipe with a string-collecting `ResponseWriter` and a note pointing at `Arc<WebUIHandler>` for cross-thread sharing. - How `requestPath` interacts with `<route>` inside a fragment. - A "what you don't get" section spelling out trade-offs (client runtime loading, module CSS dedup, inventory tracking) and pointing at the full-page recipes when those matter. Updates `docs/guide/integrations/index.md` and the sidebar in `docs/.webui-press/config.json` to surface the new page. No code changes; docs-only.
dc1197f to
d9a2b85
Compare
|
This is not how we do embedded fragments, we already support partial rendering, which is described in the docs, I Don't belive we need another doc for just this, we expose a way to get fragments. |
mohamedmansour
left a comment
There was a problem hiding this comment.
We already have docs explaining how to get partial fragments
|
Thanks for the review @mohamedmansour. Closing this PR per your preference for inline updates rather than a new page. For the record (not arguing the outcome, just making sure the rationale is captured for future readers of this thread):
So the primitives for embedded fragment rendering are different from That said, two small things in this PR's content are genuinely missing from the existing integration pages and would be helpful to keep:
Will land those two clarifications inline in Closing this one. |
|
Follow-up PR with the two inline clarifications is open at #308. |
What
New docs page:
docs/guide/integrations/fragments.md. Linked fromdocs/guide/integrations/index.mdand added to the Language Integrations sidebar indocs/.webui-press/config.json.The page walks through the "render one named fragment from a non-WebUI host" use case for both Node and Rust, plus a "what you don't get" section that points adopters back at the full-page recipes when they outgrow embedded mode.
Why
WebUI already supports this use case via the
entryoption (Noderender/renderStream) andRenderOptions::new(entry, request_path)plus a customResponseWriter(Rust). The primitives are correct - they're just not called out anywhere.I'm integrating WebUI into an embedded host. The integration is intentionally one component (a streamed list item inside a chat-style response stream) embedded inside a much larger non-WebUI host. I went looking for "how do I render exactly one named fragment without taking over the page" and didn't find a page for it. After reading the source I confirmed the primitives are right there - this PR is the missing recipe page so the next embedded adopter doesn't have to do the same source-reading exercise.
Stylistic notes:
{{outside fenced code blocks.integrations/.HandlerResult<()>from chore: correct rust integration docs to match published crate #295 - if chore: correct rust integration docs to match published crate #295 doesn't land, this PR will need a follow-up to change those return types towebui_handler::Result<()>.How I tested
I haven't run
pnpm buildagainst the docs locally - I'd appreciate a CI run to confirm the sidebar entry and links resolve correctly.Notes
users/janechu/add-fragment-rendering-docs-pageper my host repo's agent-driven branch convention.