renderToStream
Returns a ReadableStream<string>: the shell first, as a single chunk, then one
chunk per fragment as each resolves.
Signature#
import { renderToStream } from "@vincle/flow";
function renderToStream(
node: () => JSX.Element,
adapter: StreamingAdapter,
opts?: FlowOptions & { mode?: "full" | "fragment" },
): ReadableStream<string>;
Options#
| Option | Type | Default | Description |
|---|---|---|---|
signal |
AbortSignal |
N/A | Signal to abort the stream |
onError |
FlowOptions["onError"] |
N/A | Handler for fragment / stream render errors |
defaultTimeout |
number |
N/A | Per-fragment render timeout in ms |
mode |
"full" | "fragment" |
"full" |
"fragment" emits neither shell nor close |
FlowOptions is { signal?, onError?, defaultTimeout? }. The adapter is a
required second argument, not an option. Options are validated at the call,
before anything renders: see Error handling.
Usage#
import { Slot, Defer, renderToStream } from "@vincle/flow";
import { NativeAdapter } from "@vincle/flow/adapters";
declare function fetchComments(): Promise<{ text: string }[]>;
async function Comments() {
const items = await fetchComments();
return (
<ul>
{items.map((c) => (
<li>{c.text}</li>
))}
</ul>
);
}
// <Slot> declares the placeholder with fallback content in the shell.
// <Defer> pushes the real content, which replaces it when resolved.
function Page() {
return (
<html>
<body>
<h1>My page</h1>
<Slot name="comments">
<p>Loading comments…</p>
</Slot>
<Defer target="comments">{() => <Comments />}</Defer>
</body>
</html>
);
}
const stream = renderToStream(() => <Page />, NativeAdapter);
// e.g. Node: for await (const chunk of stream) res.write(chunk);
It returns the stream only: headers are yours to set, or use
serve(), which sets content-type: text/html; charset=utf-8.
The shell is one chunk#
The shell is never streamed progressively, transformShell included: it is
rendered in full, <head> and all, and only then emitted. A fully synchronous
page is a single chunk. Only fragments arrive later. Async siblings in the
shell overlap (core's rule) but their output stays in document order; for
regions that should stream in later and patch into place, use
<Defer> and <Slot>.
A <Defer> whose content is an AsyncIterable streams one patch per item,
with its merge type, and keeps the stream open until the iterable is
exhausted or the client disconnects.