Skip to content

A client-only page

A single-page app has no server step where it could paste a fragment in before the page ships. It can still embed droplets: the browser loads the droplets server’s /index.js, and the page either writes the droplet elements itself or fetches the fragments and inserts them. This page builds that with React and Vite, after examples/hosts/react-vite, which embeds the Svelte example’s droplets from http://localhost:8000. Nothing in it is React-specific: any page that runs JavaScript does the same.

Two settings in the droplets server’s droplets.config.ts matter here:

// droplets.config.ts of the droplets server (examples/frameworks/svelte)
import { config } from "@dropletsjs/droplets";
export default config({
element: "djs-svelte",
cors: true,
});
  • element is the custom element’s tag name (djs-droplet by default). The page writes it, so it has to know it.
  • cors lets a page on another origin import /index.js and the droplet bundles, and request _data and /api/*. true allows any origin; Hono cors() options ({ origin: ["https://app.example.com"] }) restrict it. Without cors, the page must reach the droplets routes on its own origin (see Same origin through a proxy).

The droplets are ordinary droplets. A droplet that only makes sense in the browser says so with ssr = false in its component: the server never renders it, and a fragment for it is an empty element carrying its data. The Svelte example’s client droplet is one:

src/droplets/client/+droplet.svelte
<script module lang="ts">
export const ssr = false;
export const hydrate = true;
</script>

A droplet with no framework at all is a script droplet (+droplet.script.ts): it is always client only, and its default export runs with (data, el).

/index.js defines the element. Load it once per page, as a module, from the droplets server. Every droplet element then loads its bundle, stylesheet and data from the place that /index.js came from, path prefix included:

src/droplets.tsx
export const DROPLETS_URL: string = import.meta.env.VITE_DROPLETS_URL ?? "http://localhost:8000";
export const DROPLETS_ELEMENT: string = import.meta.env.VITE_DROPLETS_ELEMENT ?? "djs-svelte";
let clientLoaded = false;
export function ensureDropletsClient(origin = DROPLETS_URL): void {
const src = `${origin}/index.js`;
if (clientLoaded || document.querySelector(`script[src="${src}"]`)) return;
clientLoaded = true;
const script = document.createElement("script");
script.type = "module";
script.src = src;
document.head.appendChild(script);
}

A static page writes the tag in its HTML instead:

<script type="module" src="http://localhost:8000/index.js"></script>

The element needs the droplet id and its props:

// src/droplets.tsx, client mode
const encodeContext = (props: Record<string, unknown>) =>
btoa(String.fromCharCode(...new TextEncoder().encode(JSON.stringify({ props }))));
const element = document.createElement(DROPLETS_ELEMENT);
element.dataset["droplet"] = id;
element.dataset["dropletContext"] = encodeContext(props);
target.replaceChildren(element);
Attribute What it holds
data-droplet The droplet id. An id the build does not have leaves the element inert.
data-droplet-props The props as plain JSON: data-droplet-props='{"who":"Ana"}'.
data-droplet-context Base64 of the UTF-8 JSON { "host": …, "props": { … } }; host is optional. Used before data-droplet-props when both are set; one that does not parse is logged and data-droplet-props is read instead.
data-droplet-hydrate Optional, over the droplet’s own hydrate flag: "true" (or empty) at once, "visible" when the element is about to scroll into view, "interactive" on the first interaction (at once for an element the page writes, which has no server markup to interact with), "false" never, except for a script droplet. It cannot wake a droplet whose flag is hydrate = false, which ships no bundle.

The attributes are read once, when the element connects; changing them later does nothing. To show other props, replace the element.

What the element then does, with no server markup to adopt:

  1. it runs the props schema and the universal load (+droplet.ts) in the browser, with host set to the page’s URL without its hash;
  2. when the droplet has a +droplet.server.ts, it requests POST <location>/droplets/<id>/_data with the JSON body { host, props };
  3. it adds the droplet’s stylesheet inside itself and waits for it;
  4. it mounts the component. Vue, React, Solid and Hono JSX hand it data as a promise, and Svelte does in its async mode; the other renderers wait for it and hand it the value (see each renderer’s page).

Nothing shows until the bundle has loaded. A droplet with hydrate = false has no browser bundle, so an element the page writes for it renders nothing: fetch its fragment instead.

To show the server’s HTML at once and hydrate it after, fetch the fragment from the browser and insert it. Insert only an HTML answer: a 2xx, or a 500, which carries the droplet’s error page; a 400 or 404 is text that may echo the props. Never follow a redirect (redirect: "manual"): its target is opaque in the browser and could be a page. Parse the fragment through a <template>, so the element upgrades when it enters the document:

// src/droplets.tsx, fragment mode
const url = new URL(`/droplets/${encodeURIComponent(id)}`, origin);
for (const [key, value] of Object.entries(props)) url.searchParams.set(key, String(value));
fetch(url, { signal: controller.signal, redirect: "manual", headers: { accept: "text/html" } }).then(async (response) => {
if (response.type === "opaqueredirect") throw new Error("redirected");
const isFragment =
(response.ok || response.status === 500) && (response.headers.get("content-type") ?? "").startsWith("text/html");
if (!isFragment) throw new Error(`HTTP ${response.status}`);
const template = document.createElement("template");
template.innerHTML = await response.text();
target.replaceChildren(template.content);
});

The fragment carries the droplet’s data inline, so a hydrating droplet needs no _data request, and a hydrate = false droplet shows its markup with no JavaScript of its own. The request goes from the browser straight to the droplets server, so the URLs it writes are on that server’s own origin; no x-droplet-location is involved.

The page’s framework owns a wrapper; the droplet element owns everything inside it. In React, render an empty <div ref> and put the element or the fragment into it from an effect, clearing it in the cleanup, so React never re-renders the element’s children:

// src/droplets.tsx (trimmed)
export function Droplet({ id, props = {}, mode = "fragment", origin = DROPLETS_URL }: DropletProps) {
const host = useRef<HTMLDivElement>(null);
const propsKey = JSON.stringify(props);
useEffect(() => {
ensureDropletsClient(origin);
const target = host.current;
if (!target) return;
// client mode (step 3) or fragment mode (step 4)
return () => target.replaceChildren();
}, [id, mode, origin, propsKey]);
return <div ref={host} data-react-host={id} />;
}
src/App.tsx
<Droplet id="ssr-hydrate" props={{ who }} />
<Droplet id="client" mode="client" />

When an element leaves the page, its droplet unmounts; a new element with new props mounts again.

A droplets server on another origin gets no cookies from these requests: the element’s _data request and a cross-origin fetch go out without credentials. When droplets need the visitor’s cookies (a cart, a login), serve the droplets routes under the page’s own origin instead. The shop pages of the React example do that: vite dev, vite preview and the image’s nginx proxy /index.js, /env.js, /index.css, /droplets/*, /assets/* and /api/* to the shop, with a fixed x-droplet-location, and the app loads /index.js from its own origin. The app’s own build output then goes under another folder (build.assetsDir: "app"), since /assets/* is the droplets server’s. React + Vite has that setup, and Any other stack the headers a proxy passes on.

The page renders in the browser, so without JavaScript it shows nothing, not even the droplets whose fragments it would insert. Where the first paint or search engines matter, render the page on a server and paste the fragments in there: see Ways to use Droplets.