Ways to use Droplets
A droplets server is one build of your src/droplets/ folder, running on
Node, Bun, Deno or Cloudflare Workers. It answers a few HTTP routes: the
droplet as an HTML fragment (/droplets/<id>), its data as JSON
(/droplets/<id>/_data), one module that defines the custom element
(/index.js) and the build’s files (/assets/*). What changes from one
project to the next is who asks for those routes and when. These are the
shapes the code supports; a project can use several at once.
Fragments pasted in by the host’s server
Section titled “Fragments pasted in by the host’s server”The host renders its page on its own server (PHP, Rails, Django, Express, WordPress, Next.js, anything that speaks HTTP). For each droplet it fetches the fragment, pastes it into the page, and adds the one script tag:
<!-- the host's template --><main> <?= $fragment ?> <!-- GET http://droplets:8000/droplets/greeting?who=Ana --></main><script type="module" src="https://drops.example.com/index.js"></script>The page arrives with the droplet’s HTML already in it, so it shows before
any JavaScript runs. In the browser, the element hydrates the markup from the
data the fragment carries inline, without a second request; a droplet with
hydrate = false loads no bundle of its own and stays the server’s HTML.
What the host does:
- fetches
GET /droplets/<id>?prop=value, orPOST /droplets/<id>with a JSON body{ "props": { … } }for props that do not fit in a query string; - tells the droplets server its droplet location, the URL the browser
reaches it at, either with
x-droplet-locationon each fetch (trusted only for the server’s own origin and thetrustedOrigins/DROPLETS_TRUSTED_ORIGINSentries) or once at build withlocationindroplets.config.ts; - loads
/index.jsonce per page, from that same location; - either serves the droplets routes under its own origin through a proxy
(
/index.js,/env.js,/index.css,/droplets/*,/assets/*,/api/*: no CORS, cookies are first-party), or lets the browser reach the droplets server on another origin, which then needscorsin its config.
Any other stack has the exact headers and the security checklist, the HTTP contract every route, and Hosts one worked example per stack.
Loaded from the browser
Section titled “Loaded from the browser”The host has no server of its own, or does not want to wait for one: a single-page app, a static HTML page, an htmx page. The browser asks the droplets server directly, in one of two ways:
- It fetches the fragment (
fetch,hx-get) and inserts it into the DOM. The markup and the inline data arrive together; the element upgrades on insert and hydrates. - It writes the element itself, with the droplet id and its props as
attributes. The element mounts the component in the browser and requests
_datawhen the droplet has a server load.
<script type="module" src="https://drops.example.com/index.js"></script><djs-droplet data-droplet="greeting" data-droplet-props='{"who":"Ana"}'></djs-droplet>What the host does: loads /index.js from the droplets server, and either
inserts fragments or writes elements. A droplets server on another origin
needs cors. A client-only page walks through it
with a React app, and the htmx host swaps fragments
in with hx-get.
Prerendered at build
Section titled “Prerendered at build”A droplet with prerender = true in its component and an entries
function in +droplet.server.ts is rendered at vite build for each props
set entries returns. The droplets server then answers those props from the
stored render, without running the load or the component, and renders any
other props live, as it would without prerendering.
export const entries = async () => (await allSlugs()).map((slug) => ({ props: { slug } }));What the host does: nothing different. It fetches the same fragment from the
same URL, in any of the shapes on this page; only the server’s work behind
it changes. A render that needs the page it is embedded in reads host,
which an entry can name, or host in droplets.config.ts fixes for every
render. Prerendering has the details.
A droplets server on its own
Section titled “A droplets server on its own”The droplets server can also be the page. In production and under
vite preview, / serves the index page: the file index in
droplets.config.ts names, else index.html in the project root, else a
small placeholder (index: false answers 404). That file is served as
written, so it is a plain HTML page that loads /index.js and writes the
droplet elements; on the same origin it needs no CORS and no
x-droplet-location.
A built Node server can also run inside another Node server: importing
dist/server.js does not listen, and its default export is { fetch }, a
Request => Promise<Response> handler, so an Express app mounts it on
its own origin and renders fragments in-process with
droplets.fetch(new Request(url)), with no HTTP round trip. Under vite dev,
/ belongs to the devtools page when @dropletsjs/devtools is installed.
Deployment covers both, and the
Express host runs the second one.
Several frameworks in one project
Section titled “Several frameworks in one project”The renderers you list in vite.config.ts work side by side: a
+droplet.svelte, a +droplet.vue and a +droplet.tsx can live in the same
src/droplets/, build into one server and render on one page. Each droplet
uses one framework, and so does everything it imports apart from
framework-neutral code; the build refuses a droplet that reaches another
framework’s files or packages, naming the import chain.
What the host does: nothing different. Every droplet, whatever its
framework, is the same element and the same routes, and the page loads one
/index.js for all of them; each droplet’s bundle carries only its own
framework. Renderers has the rules for shared extensions
such as .tsx, and the shop example puts six frameworks in one project.
Several servers on one page
Section titled “Several servers on one page”A page can embed droplets from more than one droplets server. Each server
names its element with element in droplets.config.ts (djs-droplet by
default), and each element loads from where its own server’s /index.js
came from, so give every server a distinct element. See
In the browser.