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.
The two steps
Section titled “The two steps”- On your server, for each droplet on the page: request
GET <droplets server>/droplets/<id>?<props>with the headers below. If the answer istext/html, paste its body where the droplet goes. - 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.
The headers, in and out
Section titled “The headers, in and out”| 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 fetch
Section titled “The fetch”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 paths to proxy
Section titled “The paths to proxy”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.
The environment
Section titled “The environment”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.
Security checklist
Section titled “Security checklist”- Write
x-droplet-locationout in your config, never pass on a client’s or build it fromHost, and list it inDROPLETS_TRUSTED_ORIGINS. - Keep the droplets server reachable only through your server and your proxy.
- Paste only
text/htmlanswers, and never follow a fragment’s redirect. - Forward the browser’s
Cookie, passSet-Cookieon without aDomain, and send pages with fragments asprivate, no-store. - Keep
Referrer-Policyat the defaultstrict-origin-when-cross-originon 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.
Worked versions
Section titled “Worked versions”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:
- JavaScript / TypeScript: Express, Next.js, SvelteKit, Astro, React + Vite
- Python: FastAPI
- PHP: PHP, WordPress
- Ruby: Sinatra
- No backend code: nginx, htmx, Static HTML, Site builders
The HTTP contract has every route and status.