serve
Builds a Response from a page function, through renderToStream, with
optional content negotiation (HTMX).
Signature#
import { serve } from "@vincle/flow/http";
function serve(
req: Request,
page: (n: Negotiation) => JSX.Element,
adapter: StreamingAdapter,
opts?: FlowOptions & ResponseInit & { negotiate?: Negotiate; mode?: "full" | "fragment" },
): Promise<Response>;
Parameters#
| Param | Type | Description |
|---|---|---|
req |
Request |
Incoming HTTP request |
page |
(n: Negotiation) => JSX.Element |
Page component function |
adapter |
StreamingAdapter |
Adapter for encoding fragments |
opts |
FlowOptions & ResponseInit & { negotiate?: Negotiate; mode?: "full" | "fragment" } |
Optional flow options, headers, mode |
Options are validated at the call, before anything renders: see Error handling.
Usage#
import { serve } from "@vincle/flow/http";
import { NativeAdapter } from "@vincle/flow/adapters";
Bun.serve({
port: 3000,
fetch(req) {
return serve(req, () => <HomePage />, NativeAdapter);
},
});
With HTMX negotiation#
import { serve, negotiateHtmx } from "@vincle/flow/http";
import { HtmxAdapter } from "@vincle/flow/adapters";
Bun.serve({
port: 3000,
fetch(req) {
return serve(req, () => <Page />, HtmxAdapter, {
negotiate: negotiateHtmx,
});
},
});
HTMX sends HX-Target to indicate which fragment a request expects. The negotiator extracts it and sets Vary: HX-Target so shared caches never serve a fragment response to a full-page navigation.
With custom negotiation#
Write your own negotiator for any client library that uses custom headers:
import type { Negotiate } from "@vincle/flow";
const negotiateMyLib: Negotiate = (req) => {
const fragment = req.headers.get("X-Fragment-Id") ?? undefined;
return {
headers: { Vary: "X-Fragment-Id" },
target: fragment,
};
};
The Vary header is unioned with existing Vary values (not overwritten), so multiple negotiators or manual headers never corrupt shared-cache keys.
With custom error handler#
serve(req, () => <Page />, NativeAdapter, {
onError: (error, { id, kind }) => {
console.error(`Fragment ${id} failed:`, error);
return <p>Unavailable</p>;
},
});
With headers#
serve(req, () => <Page />, NativeAdapter, {
headers: { "X-Custom": "value" },
status: 200,
});
Options#
| Option | Type | Default | Description |
|---|---|---|---|
signal |
AbortSignal |
N/A | Abort all pending renders |
onError |
(error, info) => JSX.Element | void |
N/A | Per-fragment error handler |
defaultTimeout |
number |
N/A | Per-fragment timeout (ms) |
negotiate |
(req: Request) => Negotiation |
N/A | Extract per-request hints |
mode |
"full" | "fragment" |
"full" |
Render full page or fragment-only |
headers |
HeadersInit |
N/A | Additional response headers |
status |
number |
200 |
Response status code |
statusText |
string |
N/A | Response status text |
The response body is a stream: the shell is flushed immediately, the browser starts parsing HTML while fragments are still rendering. The content-type header is set to text/html; charset=utf-8 automatically.