Skip to content

docs: add embedded fragment rendering recipe page#299

Closed
janechu wants to merge 1 commit into
mainfrom
users/janechu/add-fragment-rendering-docs-page
Closed

docs: add embedded fragment rendering recipe page#299
janechu wants to merge 1 commit into
mainfrom
users/janechu/add-fragment-rendering-docs-page

Conversation

@janechu
Copy link
Copy Markdown
Contributor

@janechu janechu commented May 16, 2026

What

New docs page: docs/guide/integrations/fragments.md. Linked from docs/guide/integrations/index.md and added to the Language Integrations sidebar in docs/.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 entry option (Node render / renderStream) and RenderOptions::new(entry, request_path) plus a custom ResponseWriter (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:

How I tested

I haven't run pnpm build against the docs locally - I'd appreciate a CI run to confirm the sidebar entry and links resolve correctly.

Notes

@janechu janechu marked this pull request as ready for review May 16, 2026 14:36
@janechu janechu force-pushed the users/janechu/add-fragment-rendering-docs-page branch from effa56b to dc1197f Compare May 16, 2026 14:42
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.
@mohamedmansour
Copy link
Copy Markdown
Contributor

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.

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.

We already have docs explaining how to get partial fragments

@janechu
Copy link
Copy Markdown
Contributor Author

janechu commented May 19, 2026

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): renderPartial and the entry-based render/renderStream path actually serve different use cases, so the existing partial-rendering docs don't fully cover what this PR was after.

  • renderPartial (docs/guide/concepts/routing.md) returns a JSON object ({state, templates, inventory, path, chain, cacheTags}) consumed by the WebUI client-side router during in-app navigation. It assumes the page is already a WebUI app with the framework runtime loaded.
  • render / renderStream with entry: '<fragment-id>.html' (Node) and WebUIHandler::handle + RenderOptions::new(entry, request_path) (Rust) return HTML that a non-WebUI host can splice into its own response. That's what this PR was documenting.

So the primitives for embedded fragment rendering are different from renderPartial — but you're right that they're already exposed in the existing node.md and rust.md integration pages via the entry option, and the integration page already says "Fragment ID to start rendering from." A separate recipe page is overkill given that.

That said, two small things in this PR's content are genuinely missing from the existing integration pages and would be helpful to keep:

  1. entry accepts any fragment key, not just index.html — currently the existing examples only ever show 'index.html', which underdocs the API.
  2. For FAST-v3, an <f-template name="my-component"> block is not itself a fragment (components map, not fragments map); to render a single component into an embedded host you need a thin wrapper HTML file. Adopters trying to pass an <f-template> block directly as entry will hit MissingFragment and have to read source to figure out why.

Will land those two clarifications inline in node.md and rust.md as a small focused follow-up PR. Linking it back here when it's open.

Closing this one.

@janechu
Copy link
Copy Markdown
Contributor Author

janechu commented May 19, 2026

Follow-up PR with the two inline clarifications is open at #308.

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