Skip to content

chore: correct node integration docs to match published render() signature#296

Merged
mohamedmansour merged 1 commit into
mainfrom
users/janechu/fix-node-integration-docs
May 16, 2026
Merged

chore: correct node integration docs to match published render() signature#296
mohamedmansour merged 1 commit into
mainfrom
users/janechu/fix-node-integration-docs

Conversation

@janechu
Copy link
Copy Markdown
Contributor

@janechu janechu commented May 16, 2026

What

Rewrite the three framework examples and the API Reference table in docs/guide/integrations/node.md to match the actual signature of render() / renderStream() exported from @microsoft/webui.

Why

I'm integrating WebUI into a non-WebUI Node host, and the published Node integration page is the first thing a new adopter reads. The page currently teaches:

render(protocol, JSON.stringify(state), entry, requestPath, onChunk)

but packages/webui/src/index.ts actually exports:

render(protocol: Buffer, state: object | string, options?: RenderOptions): string
renderStream(protocol: Buffer, state: object | string, onChunk: (html: string) => void, options?: RenderOptions): void

Copying any of the three examples into a fresh project does not work, in three different ways:

  1. entry, requestPath, and plugin are properties on a RenderOptions object, not positional args.
  2. state accepts an object directly, so JSON.stringify is unnecessary boilerplate that suggests the API requires it.
  3. render returns the full HTML as a string; only renderStream invokes a chunk callback. The Bun and Deno examples collect chunks into an array and .join('') them, which is doubly confusing because that's exactly what render already does internally.

How I tested

packages/webui/src/index.ts is the source of truth for the exported signatures. The three rewritten examples match the exported types and use the correct entry point (renderStream where streaming is desired, render for accumulate-then-respond).

Notes

…ature

All three framework examples in docs/guide/integrations/node.md called
`render(protocol, JSON.stringify(state), entry, requestPath, onChunk)`
with positional arguments and a streaming callback. The published API
in @microsoft/webui (per packages/webui/src/index.ts) is:

  render(protocol, state, options?): string
  renderStream(protocol, state, onChunk, options?): void

`state` accepts an object directly (auto-stringified). `entry`,
`requestPath`, and `plugin` are members of a RenderOptions object.
`render` returns the rendered HTML; only `renderStream` uses a chunk
callback.

This PR:

- Rewrites the Node.js example to use renderStream() (preserves the
  streaming flavor of the original).
- Rewrites the Bun and Deno examples to use render() (simpler — they
  construct a Response from a string anyway).
- Updates the API Reference table to show both render and
  renderStream with correct signatures, adds a RenderOptions table,
  and notes that state accepts an object or string.

No code changes; docs-only.
@janechu janechu marked this pull request as ready for review May 16, 2026 14:40
@janechu janechu force-pushed the users/janechu/fix-node-integration-docs branch from 732e5c0 to 7aab040 Compare May 16, 2026 14:42
@mohamedmansour mohamedmansour merged commit cb99161 into main May 16, 2026
21 checks passed
@mohamedmansour mohamedmansour deleted the users/janechu/fix-node-integration-docs branch May 16, 2026 16:29
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