Skip to content
Vincle
Esc

Loading…

    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.