Adapters
An adapter controls how placeholders and patches are encoded in the HTML, in the markup a specific client (a library, the browser, a CDN) recognises and acts on.
Vincle ships five built-in adapters. Import from @vincle/flow/adapters:
import {
TurboAdapter, // Turbo Streams: <turbo-frame> / <turbo-stream>, morph on Turbo >= 8
HtmxAdapter, // HTMX: hx-get / hx-swap-oob, morph on htmx >= 4
NativeAdapter, // <template data-for> + inline polyfill, all 6 positions
WebPlatformAdapter, // WICG declarative partial updates, native support required
EsiAdapter, // CDN edge composition via esi:include
} from "@vincle/flow/adapters";
Choosing an adapter#
| Adapter | Client runtime | Streaming | Merge types | Best for |
|---|---|---|---|---|
| NativeAdapter | ~1.5 kB polyfill, gzipped (auto-injected) | Yes | all 6 positions | General purpose, no extra JS |
| TurboAdapter | Hotwire Turbo | Yes | all 7 | Rails / Hotwire stack |
| HtmxAdapter | HTMX | Yes | all 7 | Django / Laravel / any backend |
| WebPlatformAdapter | None (native browser support required) | Yes | replace only | Browsers with declarative partial updates |
| EsiAdapter | None (CDN-level) | No | replace only | Varnish / CDN edge composition |
morph needs a diffing client (Turbo, HTMX); an adapter refuses a merge type it
does not support.
NativeAdapter#
Recommended for most applications. It uses the
WICG Declarative Partial Updates
format (the WICG, Web Incubator Community Group, is where browser features are
proposed before they become standards), with a polyfill injected automatically when fragments or active
<template src> / <template for> elements are present. Inert templates and
pages without deferred content do not require it.
Use Native for both static site generation (SSG: every page rendered once, at
build time, and written to disk) and streaming while native browser support is
incomplete.
Native protects templates with data-for, so browsers that implement patching
but not src cannot consume them before the polyfill. It handles both comment
and processing-instruction markers.
A static site loads the emitted fragment files. Streaming consumes complete inline patch templates and also handles external includes arriving in the page. External responses are buffered; failed requests preserve fallback content.
Once target browsers support both WICG patching and Fragment Include, switch the
render call to WebPlatformAdapter. Keep the same JSX and generated URLs and
use merge="replace", which both adapters support. WebPlatform emits standard
for attributes and adds no JavaScript.
WebPlatformAdapter#
The standard WICG format with no polyfill: the initial HTML holds a named range with
fallback content, and a matching <template for="…"> later in the response
replaces it as the browser parses it.
<?start name="comments">Loading comments…<?end>
<!-- Later in the same HTML stream: -->
<template for="comments"><p>First comment</p></template>
For a static-mode <Defer>, Vincle instead emits an external include:
<?start name="comments">Loading comments…<?end>
<template for="comments" src="/fragments/comments.html"></template>
emitFragments writes raw HTML at that URL, with no <template> wrapper.
This follows the experimental
Fragment Include proposal.
You can also render <template src="/partials/header.html" for="" /> directly
in JSX for an in-place include. Importing Flow also enables buffer, sanitize, crossorigin,
and referrerpolicy as well. Without native support, these includes remain inert.
The Native polyfill supports targeted and in-place includes, but buffers external
responses and does not implement the proposal’s sanitization API.
It needs native browser support; Google's
Declarative partial updates article
covers the motivation and browser support. For the polyfill and the other merge
positions, use NativeAdapter.
TurboAdapter#
Encodes placeholders as <turbo-frame> elements and patches as
<turbo-stream> elements, for Hotwire Turbo.
// Placeholder in shell:
// <turbo-frame id="comments">Loading…</turbo-frame>
// Patch:
// <turbo-stream action="replace" target="comments">
// <template>…</template>
// </turbo-stream>
// Patch, merge="morph" (Turbo >= 8):
// <turbo-stream action="replace" method="morph" target="comments">
// <template>…</template>
// </turbo-stream>
HtmxAdapter#
Encodes placeholders (with hx-get when the fragment has a URL, in static mode)
and patches as hx-swap-oob elements, for HTMX. An
out-of-band (OOB) swap replaces the element with the same id wherever it sits
in the page, not only the target of the request. For request negotiation, see
negotiateHtmx.
// Placeholder in shell:
// <div id="comments" hx-get="/_fragments/comments" hx-trigger="load" hx-swap="outerHTML">Loading…</div>
// Patch:
// <div id="comments" hx-swap-oob="outerHTML">…</div>
// Patch, merge="morph" (htmx >= 4):
// <div id="comments" hx-swap-oob="outerMorph">…</div>
EsiAdapter#
Encodes placeholders as <esi:include> elements. ESI (Edge Side Includes) is a
markup resolved before the page reaches the browser: an ESI-capable CDN or reverse
proxy (Varnish, Akamai, Fastly) fetches and inserts the content. Static only
(streaming: false), replace only: the origin emits one HTML template and the
edge fills in the dynamic parts.
Custom adapters#
Build your own with createAdapter from @vincle/flow/adapters:
| Export | Purpose |
|---|---|
Placeholder |
Renders the shell placeholder for a deferred fragment |
Patch |
Wraps a resolved fragment for injection into the DOM |
Frame |
Wraps a static fragment file for static site output |
capabilities |
Declares supported merge types and streaming support |
transformShell |
(Optional) Post-processes the shell before it enters the stream |
import { createAdapter } from "@vincle/flow/adapters";
const MyAdapter = createAdapter({
Placeholder: ({ id, children }) => <div data-defer={id}>{children}</div>,
Patch: ({ id, children, merge }) => (
<div data-patch={id} data-merge={merge}>
{children}
</div>
),
Frame: ({ id, children }) => <div data-frame={id}>{children}</div>,
capabilities: { streaming: true, merges: ["replace", "append"] },
});
An adapter does not implement the streaming wire: renderToStream owns it, and
capabilities.streaming: true only declares the adapter can stream.
Patch receives first, true on the boundary's first patch of the response,
while the placeholder's fallback is still in place. An adapter whose boundary
is an element should replace the placeholder's content on that patch
(innerHTML, update) instead of inserting next to it: a positioned merge would
otherwise leave the fallback standing there for the rest of the page's life. The
built-in HTMX and Turbo adapters do exactly that; the Native polyfill empties the
placeholder's range before inserting. update is the exception: it replaces the
target element's children and keeps the element, so the polyfill uses
replaceChildren on it (and on the placeholder's range when the target has no
element of its own).
transformShell can inject a client runtime or modify the shell HTML. It
receives a ShellContext, not the full flow context: just
ctx.fragments.size, so you can inject scripts only when fragments are
actually pending.