@vincle/flow
The shell is instant. Slow parts wait.
@vincle/core returns the page once every await has resolved: the slowest
query sets your time-to-first-byte. @vincle/flow, a separate package built on
the core, breaks that coupling.
You mark slow subtrees with <Defer>. The page shell ships
immediately. Fragments arrive later, each as soon as it resolves. No JavaScript
framework. No hydration. Just HTML in chunks.
Install#
npm install @vincle/flow
pnpm add @vincle/flow
bun add @vincle/flow
How it works#
Page response
Shell: immediate
<nav>, <header>, layout…
Fragment: deferred
<Slot> placeholder
Fragment: deferred
<Slot> placeholder
Shell flushed → browser starts painting
Fragment A resolves → injected into placeholder
Fragment B resolves → injected independently
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>
);
}
// The shell is sent immediately; deferred fragments stream
// in as they resolve. NativeAdapter injects a small polyfill.
const stream = renderToStream(() => <Page />, NativeAdapter);
Two rendering modes#
Streaming
Fragments arrive in the same HTTP response after the shell. One connection, progressive delivery.
renderToStream()
Static generation
Fragments are emitted as separate HTML files at build time. The browser fetches them on load.
renderToStatic()
Adapters#
An adapter controls how placeholders and patches are encoded in the HTML shell: for Turbo, HTMX, the browser's native partial updates, or a CDN's ESI (Edge Side Includes). See Adapters for the five built-in ones and how to choose.
For a quick answer, see Can I use Vincle for streaming HTML?.