Skip to content

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": … }
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:

GET /droplets/hello?who=Ana200

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.

The fragment →
Hover, focus or tap a part of the fragment, or a file.

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.

This is a live droplet served by apps/demo: rendered on its server, hydrated here.

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.

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.

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.

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.js for Node, Bun or Deno, or dist/worker.js for Cloudflare Workers.

The dev server is Vite’s own, with droplet-level hot updates layered on top, on any page that embeds a droplet.

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.

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!