Skip to content

Any other stack

A host needs nothing from Droplets but HTTP. If your stack can make a request on the server and send HTML back, it can host droplets. This page is the whole recipe; the host examples are the same recipe written out stack by stack.

  1. On your server, for each droplet on the page: request GET <droplets server>/droplets/<id>?<props> with the headers below. If the answer is text/html, paste its body where the droplet goes.
  2. In the page, once: <script type="module" src="/index.js"></script>. Every droplet element on the page then hydrates itself, and loads only its own bundle.

/index.js comes through your own origin when you proxy the droplets routes (the paths), which is what every known host does: the browser then talks to one origin, and the droplets’ cookies are first-party.

Header On Value Why
accept: text/html your request exactly that What every example sends. A GET fragment is HTML whatever accept says; on an action POST (the proxy), accept: application/json is what makes the answer JSON, so the proxy passes the browser’s accept on unchanged.
x-droplet-location your request your public origin, written out in your config: https://www.example.com The URLs the fragment writes (its stylesheet, its Link preloads, its form actions) point there. Honored only when its origin is trusted: the droplets server’s own, or listed in trustedOrigins or DROPLETS_TRUSTED_ORIGINS. A droplets server built with location in its config reads no location header: send it anyway, it costs nothing. See x-droplet-location.
Cookie your request the browser’s Cookie header, as it came The droplet’s handle and loads see the visitor’s session, cart and login.
Referer your request the page’s own URL, query included: https://www.example.com/product/mug?v=3 A handle that reads it with hostFrom gets the page as the droplet’s host. After a form posted without JavaScript, the query carries the form’s result (Post/Redirect/Get).
redirects your HTTP client not followed: redirect: "manual" A 3xx is the droplet’s answer (a moved product, a login). Answer the browser with the same status and Location. Following it would make your server request a URL someone else chose.
content-type the answer paste only text/html: a 200, or a 500 with the droplet’s error page A 400 or 404 is plain text that may echo the props. Show a note of your own instead.
Set-Cookie the answer each one passed on with your page, unchanged A droplet that sets a cookie on a GET reaches the browser only through you. Never add a Domain: the cookie belongs to your origin.
Link the answer the fragments’ Link headers joined with , on your page, or turned into <link> tags in its <head> The browser starts the droplets’ stylesheets and bundles before it reaches the elements. Optional: without it they start later.

The same steps in about twenty lines of JavaScript-flavored pseudocode. Every known host has this function in its own language:

// On your server, for each droplet the page shows.
async function fragment(page, id, props) {
const res = await fetch(`${DROPLETS_INTERNAL_URL}/droplets/${encodeURIComponent(id)}?${new URLSearchParams(props)}`, {
headers: {
accept: "text/html",
"x-droplet-location": PUBLIC_ORIGIN, // fixed, from your config: never from the request
referer: PUBLIC_ORIGIN + page.pathAndQuery,
...(page.cookie ? { cookie: page.cookie } : {}),
},
redirect: "manual",
});
for (const cookie of res.headers.getSetCookie()) page.addHeader("set-cookie", cookie);
if (res.headers.has("link")) page.addHeader("link", res.headers.get("link"));
if (res.status >= 300 && res.status < 400) return page.redirect(res.status, res.headers.get("location"));
const isFragment = (res.status === 200 || res.status === 500) && res.headers.get("content-type")?.startsWith("text/html");
return isFragment ? await res.text() : `<p>This part of the page is unavailable.</p>`;
}

And the page around it:

<script type="module" src="/index.js"></script>
…
<main>${await fragment(page, "product-card", { slug: "mug" })}</main>

Fetch several droplets in parallel (Promise.all, asyncio.gather, curl_multi, a thread each): the page waits for the slowest one, not for their sum. Send the page itself with cache-control: private, no-store: its fragments were rendered with the visitor’s cookies.

The browser asks for more than the fragment: the droplets’ code, their data, form posts and your API. Forward these paths from your origin to the droplets server, every method, body streamed:

Path What the browser asks for
/index.js A small file, no-store; it imports the element from /assets/, and /env.js when the project has public variables read at runtime
/env.js The public variables read at runtime, only when src/env.ts declares one (404 otherwise). When it exists and is not proxied, /index.js fails to load and no droplet hydrates
/index.css The shared stylesheet’s import, no-store, for a page that links it itself
/droplets/* client.js bundles, style.css, _data refreshes and form actions (POST /droplets/<id>?/name)
/assets/* The entry client, shared chunks, stylesheets, images, and public/ at /assets/public/
/api/* Your +server.ts endpoints, which $droplets/drop calls

One more only with externals: /importmap.js (and /importmap, if your server inlines the map). The rest of the routes are for servers, not browsers.

On each proxied request, set x-droplet-location to your public origin, clear Forwarded, X-Forwarded-Host, X-Forwarded-Proto and X-Forwarded-Prefix (a client could set them; the droplets server reads them after x-droplet-location, and trusts them only against its allow-list), do not follow redirects, and pass Set-Cookie back untouched. If your HTTP client decodes the body, drop content-encoding and content-length from the answer. In nginx, from examples/hosts/nginx/nginx.conf, where PUBLIC_ORIGIN is called SHOP_PUBLIC_URL:

location ~ ^/(index\.js$|env\.js$|index\.css$|droplets/|assets/|api/) {
proxy_pass http://shop;
proxy_set_header x-droplet-location ${SHOP_PUBLIC_URL};
proxy_set_header Forwarded "";
proxy_set_header X-Forwarded-Host "";
proxy_set_header X-Forwarded-Proto "";
proxy_set_header X-Forwarded-Prefix "";
}

Without a proxy, load /index.js from the droplets server’s public URL, send that URL as x-droplet-location (list its origin in the droplets server’s DROPLETS_TRUSTED_ORIGINS), and turn on cors on the droplets server: the browser then fetches bundles and data across origins, and the droplets’ cookies are third-party.

On the droplets server:

Variable Value What for
DROPLETS_TRUSTED_ORIGINS https://www.example.com, comma-separated for several The origins whose x-droplet-location it honors, and the origins whose form posts pass the Origin check. Added to trustedOrigins in droplets.config.ts, read at runtime.
DROPLETS_ENV_MAX_AGE 600 by default Seconds a browser or CDN may keep /env.js, the public variables read at runtime; 0 sends no-store. Read at runtime; an invalid value keeps 600.
DROPLETS_SECRET 32 or more random bytes Signs a form’s result on the 303 back to your page when JavaScript is off. Without it, such a post answers the droplet’s fragment instead.
PORT server.port of the config, 8000 by default Where node dist/server.js (and Bun’s) listens; deno serve picks its own port, and vite dev does not read it.

These four and DEV_DROPLETS_LOG (the level of the vite dev and vite build log) are all the framework reads. A production server logs errors only, with console.error.

On your server, two values the host examples read from their environment (Droplets does not read them, name them as you like):

Variable Example What for
DROPLETS_INTERNAL_URL http://droplets:8000 Where your server reaches the droplets server: fragment fetches and the proxy
PUBLIC_ORIGIN https://www.example.com Your pages’ public origin, where the browser reaches the proxied droplets routes: sent as x-droplet-location

The example hosts call the second one SHOP_PUBLIC_URL. Their basic pages, which load the droplets server without a proxy, use DROPLETS_PUBLIC_URL, the droplets server’s own public URL, instead.

  1. Write x-droplet-location out in your config, never pass on a client’s or build it from Host, and list it in DROPLETS_TRUSTED_ORIGINS.
  2. Keep the droplets server reachable only through your server and your proxy.
  3. Paste only text/html answers, and never follow a fragment’s redirect.
  4. Forward the browser’s Cookie, pass Set-Cookie on without a Domain, and send pages with fragments as private, no-store.
  5. Keep Referrer-Policy at the default strict-origin-when-cross-origin on pages with forms, or their posts are refused.

Security model has the reasons, and Who sees what says what a droplets server learns about the pages that embed it.

The host examples run this recipe stack by stack, each a Docker Compose project in examples/hosts/ with an end-to-end test. Start from the one closest to yours:

The HTTP contract has every route and status.