What is a droplet?
A droplet is a single component with its own URL. A droplets server hosts a folder of them and answers, for each one:
| Request | You get |
|---|---|
GET /droplets/hello?who=Ana |
The droplet as an HTML fragment, ready to paste into another page |
POST /droplets/hello |
The same fragment, with the props (and the host page) in a JSON body |
POST /droplets/hello?/name |
A form post: runs the droplet’s action name, then renders it again |
GET /droplets/hello/_data?who=Ana |
The server load’s result, as JSON: { "data": … } |
Words these docs use
Section titled “Words these docs use”| Word | Meaning |
|---|---|
| fragment | The HTML a droplets server answers for GET /droplets/<id>: the droplet element with its data and server-rendered markup, ready to paste into a page. |
| host | The server or app that embeds a droplet in its pages (nginx, Express, WordPress, a single-page app). The page itself is the host page. |
host |
In a load, the host page’s URL (a URL). In droplets.config.ts, the host page’s origin, fixed at build (A fixed host). The HTTP Host header is another thing. |
| droplet location | Where the browser reaches the droplets server: the origin, and path prefix, that /index.js was loaded from. On the server it is computed per request (a trusted x-droplet-location, else the request’s own origin), or fixed at build with location. |
x-droplet-location |
The request header a host sends with a fragment fetch: the droplet location, as the browser sees it. See x-droplet-location. |
| context | What a droplet renders with: { host, props }, carried in the fragment of a droplet that hydrates (data-droplet-payload="context") so the browser can ask for the same data again. |
| renderer | The package that renders one framework’s components: @dropletsjs/renderer-svelte, -vue, -react and the others. See Renderers. |
| element | The custom element every droplet renders in, <djs-droplet> by default, named per server with the element option. /index.js defines it. |
A droplet is one folder:
Hello, !
<djs-droplet>
The fragment is one custom element, defined by /index.js on the host page. data-droplet names the droplet after its folder; data-droplet-build and data-droplet-render name the build and this render.
<djs-droplet>
The fragment is one custom element, defined by /index.js on the host page. data-droplet names the droplet after its folder; data-droplet-build and data-droplet-render name the build and this render.
<djs-droplet data-droplet-error>
The same element, now marked data-droplet-error: what it holds is the error page. The fragment answers 500.
Inline payloads
data-droplet-payload="context" carries the props and the host, data-droplet-payload="data" the load's result, both base64 JSON. Hydration reads them, so the browser asks for nothing more.
Inline payloads
data-droplet-payload="data" now holds { error }, as handleError left it. The browser hydrates the error page from it.
Server markup
+droplet.svelte, rendered on the server into data-droplet-entry. In the browser it hydrates in place: at once, when visible, on first interaction, or never with hydrate = false.
Load data
“Ana” is what load in +droplet.server.ts returned for the props who=Ana. It runs on the server per request, or once at build when prerendered, and becomes the component's data.
The form
It posts to ?/greet on the droplets server, where actions.greet runs. Posted without JavaScript, it is answered 303 back to the page, and the droplet renders again with the result as form.
+error.svelte
The load threw, so the error page renders inside the same element, in the droplet's place. It follows the droplet's flags: rendered on the server, hydrated in the browser. error() and redirect() skip it: they answer the request.
hello/
One folder is one droplet. Its name is the id: data-droplet="hello", served at /droplets/hello.
+droplet.svelte
The component, in any of eight frameworks. It draws the greeting and the form.
Structure →+droplet.svelte
Nothing of it renders now: the error page has taken its place.
Errors →+droplet.server.ts
Server only, never in a browser bundle. load feeds the component its data; actions take its form posts.
+droplet.server.ts
Its load threw. Its handleError decides what the error page is told; without one, production says only “Internal Error”.
+error.svelte
The droplet's error boundary, in the same framework. It renders only when a load fails: switch on “load fails”.
Errors →The demo’s hello is a Svelte droplet whose server load greets who.
Here it is: the docs fetched its fragment when this page was built, and the demo’s /index.js hydrated it in your browser.
hello · Svelte
Hello docs reader!
Rendered by the demo server at , waiting for its bundle.
vite build turns the folders into one droplets server. An optional
+droplet.ts holds a props schema and a load that runs on both sides.
Every droplet is server-rendered (unless it opts out), carries its own data
inline, and is bundled on its own: the browser fetches
/droplets/hello/client.js for hello and nothing else. A page that embeds
five droplets loads five small bundles, not one big one, and a droplet that
does not hydrate loads none.
Components can be written in Svelte, Vue, Solid, React, Preact, Hono JSX, Handlebars or Lit, through renderers, or as a plain script. One project can mix them.
The unit of delivery is the component
Section titled “The unit of delivery is the component”Most frameworks deliver pages. A page owns its routing, its data loading and its JavaScript, and everything inside it has to be written in that framework.
Droplets inverts that. The component owns its route, its data loading, its error page and its JavaScript. The page is whoever asked for it: a static HTML file behind nginx, a WordPress post, a Next.js server component, a Python template. The host fetches the fragment and pastes it in; the fragment brings everything it needs to come alive.
Where it fits
Section titled “Where it fits”Droplets is a good fit when:
- Several applications, possibly in several languages, need the same interactive widgets: a login box, a product card, a chart, a comment thread.
- You want to add interactive components to an existing site piece by piece, without rewriting the pages around it.
- Teams ship UI independently: a droplets server deploys on its own schedule, and host pages pick up the new version on the next request.
It is not the right tool when you are building one application in one framework. Use that framework’s own meta-framework (SvelteKit, Nuxt, Next.js, SolidStart) for that; it does pages, forms and routing far better than a fragment server ever will.
How it is built
Section titled “How it is built”Droplets is a Vite plugin. One vite build emits:
- a client bundle per droplet that hydrates, plus a small entry script that defines the droplet custom element;
- an SSR renderer with the registry of components and their loads;
- a Hono server with your config baked in, depending on
the adapter:
dist/server.jsfor Node, Bun or Deno, ordist/worker.jsfor Cloudflare Workers.
The dev server is Vite’s own, with droplet-level hot updates layered on top, on any page that embeds a droplet.
Where it comes from
Section titled “Where it comes from”Droplets grew out of SvelteKit and keeps the patterns that work there: + files, load on the server and
on both sides, form actions with fail() and redirect(),
hooks.server.ts and hooks.client.ts, $droplets/env/*, prerendering
with entries. They are reshaped for islands of server-rendered HTML that
live inside someone else’s page, served by any stack and written in any of
eight frameworks. Droplets is an independent project, not affiliated with
Svelte or SvelteKit.
A note from the author
Section titled “A note from the author”Thanks to AI I managed to revive a POC project from February this year and move it into an actual useful project. Hope everybody enjoys it!