Streaming
Send the HTML shell immediately and stream deferred fragments inline in the same HTTP response. One connection, progressive delivery: no client-side fetch logic required.
How a streamed response arrives#
Take a page that needs two slow queries, comments and recommendations. If the
page awaits them itself, nothing is sent until both have resolved. If each
query runs in a <Defer> given as a function, the shell is sent first, each
query starts once the shell is rendered, and each part is sent as soon as its own
query resolves.
Both queries awaited in the page
Each query in a <Defer>
In both cases the page runs the same two queries. Here comments finishes before recommendations, so its patch is sent first.
What decides the order:
- Everything outside a
<Defer>belongs to the shell. Anawaitthere delays the shell, so keep slow work inside a<Defer>. - Each
<Defer>runs on its own, and patches are sent in the order they finish, not the order they appear in the page. - A
<Defer>nested in another one is sent after its parent.
When to stream#
Streaming is the right choice when:
- Time-to-first-byte matters (the shell paints before slow queries finish)
- Fragments depend on request-time data (user-specific content, live results)
- You want a single HTTP connection from shell through last fragment
- The client has no JS runtime (or you want to minimise it)
If your content is known at build time and you want zero server infrastructure, use Static generation instead.
renderToStream#
Returns a ReadableStream<string>. The adapter is required: pass a streaming
adapter (e.g. NativeAdapter) as the second argument. NativeAdapter injects
its small polyfill only when fragments are present.
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);
The shell is rendered fully, then sent as a single chunk. Each fragment follows
as soon as it resolves. renderToStream returns the stream only: headers are
yours to set, or use serve(), which sets them.
To send the stream over HTTP, with serve() or a Node.js server (Express,
Fastify, Hono, anything built on node:http), see
HTTP serving.
Async iterables: streaming sequences#
A <Defer> whose content is an AsyncIterable streams one patch per yielded
item, until the iterable ends or the client disconnects. Every patch carries the
<Defer>'s merge; for a different merge per chunk, use separate <Defer>s.
import { Defer } from "@vincle/flow";
declare function fetchRows(page: number): Promise<{ id: number; name: string }[]>;
function Feed() {
return (
<Defer target="feed" merge="append">
{async function* () {
let page = 1;
while (true) {
const rows = await fetchRows(page++);
if (rows.length === 0) break;
for (const row of rows) {
yield <tr key={row.id}>{row.name}</tr>;
}
}
}}
</Defer>
);
}
The source need not be a fixed dataset: anything adaptable into an
AsyncIterable works, including a live event source. Node's events.on turns
an EventEmitter into one; pass it the factory's signal (the request's abort
signal combined with the fragment's timeout) so the listener stops when either
fires:
import { Defer } from "@vincle/flow";
import { on, type EventEmitter } from "node:events";
declare const priceFeed: EventEmitter; // emits "price" with { symbol, value }
function LivePrice() {
return (
<Defer target="price">
{async function* (signal) {
for await (const [price] of on(priceFeed, "price", { signal })) {
yield (
<span>
{price.symbol}: {price.value}
</span>
);
}
}}
</Defer>
);
}