Skip to content

In the browser

/index.js defines one custom element, <djs-droplet> by default (the element option renames it). Everything below is that element’s work; setup of your own that must come first goes in src/hooks.client.ts. /index.js itself is a file of the build, a few lines sent no-store: it imports /env.js (only when public variables are read at runtime) and the element under a name unique to the build, which is cached for good, then records the URL it was loaded from.

An optional file (.ts, .mts, .js or .mjs) for setup that runs before everything else on the page: a gtag setup, or a global such as the shop’s window.shopMessageQueue. A page built from islands has no index.html of its own, so this is where the script SvelteKit would put in app.html goes.

src/hooks.client.ts
import type { ClientInit } from "@dropletsjs/droplets";
import { MessageQueue } from "./lib/message-queue.ts";
export const init: ClientInit = () => {
window.shopMessageQueue ??= new MessageQueue();
};
  • /index.js calls init() synchronously, first thing, before it defines the droplet element: before any droplet hydrates or mounts. The public variables read at runtime ($droplets/env/public) are already there.
  • It may be async, but Droplets never waits for it. Its type is () => void | Promise<void>: /index.js calls it and carries on at once, and when it returns a promise, a rejection is only logged.
  • When it throws, the error is logged (console.error) and the droplets start all the same.
  • It runs in the browser only, with the DOM and nothing from the server: no request, no props, no load data. Server state exists only within a request, through a droplet’s context or its load data, never here.
  • It runs once per /index.js: the browser runs a module URL once per page. The same app served from two locations is two resources, and each runs its own init.
  • It is browser code: importing a server file (*.server.*, a file under a server/ folder, $droplets/env/private) fails the build and the dev server, as from any droplet. See Server-only code.
  • Under vite dev, editing the file shows a notice with Reload page, since init runs once per page. With dev.strategy: "reload" or "remount" the page reloads; with "manual" the console says so. See Hot updates.

Without the file, /index.js is exactly what it would be otherwise: no code is added.

From the script tag to a live droplet:

A droplet element's life on the page/index.js runs once per page: it calls init() of src/hooks.client.ts, then defines the djs-droplet element. Each element that connects checks its droplet: one this build does not know, or markup from another build, is left as it is (another build also dispatches droplets:stale). Then the mode: data-droplet-hydrate on the element, else the droplet's hydrate flag. False: it stays as the server rendered it and no bundle loads. Visible waits until it is about to scroll into view, interactive until the first interaction; true goes on at once. It imports /droplets/<id>/client.js, which runs +droplet.ts, takes its data from the fragment's inline payload, or else posts to /droplets/<id>/_data, and hydrates the server markup in place, or mounts fresh when there is none./index.jsruns init() of hooks.client.ts, then defines theelement<djs-droplet> connectsa droplet of this build?noleft as it isanother build: droplets:staleyesdata-droplet-hydrate, elsethe flagfalsestays server HTMLno bundle loadstrue, visible, interactivewaits, when lazyvisible: about to scroll into view; interactive:the first interaction/droplets/<id>/client.jsimported, runs +droplet.tsthe datainline in the fragment; else POST/droplets/<id>/_datahydrates, or mounts freshhydrates the server markup; mounts whenthere is noneA droplet element's life on the page/index.js runs once per page: it calls init() of src/hooks.client.ts, then defines the djs-droplet element. Each element that connects checks its droplet: one this build does not know, or markup from another build, is left as it is (another build also dispatches droplets:stale). Then the mode: data-droplet-hydrate on the element, else the droplet's hydrate flag. False: it stays as the server rendered it and no bundle loads. Visible waits until it is about to scroll into view, interactive until the first interaction; true goes on at once. It imports /droplets/<id>/client.js, which runs +droplet.ts, takes its data from the fragment's inline payload, or else posts to /droplets/<id>/_data, and hydrates the server markup in place, or mounts fresh when there is none./index.jsruns init() of hooks.client.ts,then defines the element<djs-droplet> connectsa droplet of thisbuild?noleft as it isanother build:droplets:staleyesdata-droplet-hydrate,else the flagfalsestays serverHTMLno bundle loadstrue, visible,interactivewaits, when lazyvisible: near the viewport;interactive: the firstinteraction/droplets/<id>/client.jsimported, runs +droplet.tsthe datainline in the fragment; elsePOST /droplets/<id>/_datahydrates, or mountsfreshhydrates the server markup;mounts when there is none
From the script tag to a live droplet: a lazy mode waits, false never loads a bundle.

When a droplet element connects to the page, it:

  1. takes where to load from: the URL /index.js was loaded from, path prefix included (before /index.js recorded it, the root of the build its bundle came from, prefix included). The markup has no say in it;
  2. links the droplet’s stylesheet inside the element when the markup did not bring it (see Styles);
  3. moves the host’s children into place (see Host children);
  4. if the droplet hydrates, imports /droplets/<id>/client.js, runs +droplet.ts, and hydrates the server markup, or mounts fresh when there is none.

Data comes from the inline payload when the server rendered the droplet. The element only requests /droplets/<id>/_data for droplets with +droplet.server.ts when nothing came inline.

A React counter, server-rendered with start: 3: until the bundle has hydrated it, the buttons are server HTML (and a click is held); after, the count lives in this tab.

counter · React

3

Server HTML: the buttons wake up once React hydrates.

This is a live droplet served by apps/demo: React, hydrated from its own bundle.

A droplet the build does not know is left untouched. Removing an element unmounts its droplet; an element removed and re-inserted in the same task (a framework re-ordering its parent) keeps its instance.

Nothing goes into the host’s <head>. A fragment carries <link rel="stylesheet" data-droplet-style> to /droplets/<id>/style.css inside the element, ahead of its markup: the browser applies it before it paints that markup, and it stays with the element wherever the host moves it. It imports the shared stylesheet first, then the droplet’s own; components shared by several droplets have their styles in stylesheets of their own, so every droplet that uses them gets them, and the browser downloads each file once.

An element without that link (one the host wrote itself) adds it from the build’s registry, with the stylesheets style.css imports preloaded beside it so they download at once rather than after it, all alongside the bundle and the data. The droplet mounts once the stylesheet has loaded, or failed: it never shows unstyled. Server markup hydrates without waiting; it is already on screen.

In vite dev, styles come with the JavaScript instead, as Vite injects them: the shared stylesheet with /index.js, component styles with the droplet’s bundle. Fragments link no stylesheet then, and Vite’s <style> tags are the one thing in <head>, in dev only.

Styling covers the stylesheets themselves: scoping, theming from the host page, Tailwind and each renderer.

export const hydrate = "visible" or "interactive" defers the bundle:

Mode Loads when
true at once
"visible" the element is about to scroll into view: 200px ahead, or 1000px ahead when there is no server markup to show meanwhile
"interactive" the first pointerdown, focusin, keydown or click on the droplet’s own markup (not the host’s children, not a nested droplet). Without server markup there is nothing to interact with, so it mounts at once.
false never: no bundle exists

A host overrides the mode per element:

<djs-droplet data-droplet="comments" data-droplet-hydrate="visible">…</djs-droplet>

data-droplet-hydrate takes true, false, visible or interactive; an unknown value warns in dev. It cannot turn hydration on for a droplet that ships no bundle (hydrate = false in the component), and false does not stop a script droplet, which only runs in the browser.

Between the server markup appearing and the bundle hydrating it, a click would hit dead HTML. The element holds them instead:

  • every click on its own server markup is captured while a hydrating droplet (or its error page) loads; the default action is prevented, the event still bubbles to the host;
  • once hydrated, the clicks are dispatched again, in order, on the same nodes, at the same position relative to each node’s box. When the engine rendered the markup anew instead of adopting it (Hono JSX does), a click goes to the element in the node’s place under the droplet’s root, provided it is the same kind of element;
  • a click is kept for 1500 ms, counted from the later of the click and the start of hydration (bundle and data in), so a slow download does not eat it. A click older than 10 s, or on a node that is gone with nothing of its kind in its place, is dropped;
  • repeated single clicks on one node more than 400 ms apart (someone clicking again because nothing happened) replay as one.

Clicks on the host’s children and inside nested droplets are left alone, as are client-only droplets and droplets that never hydrate. With hydrate = "interactive", the click that triggers hydration is held and replayed the same way.

A droplet’s forms post to its actions as any form does: the browser navigates to the action’s URL. The element intercepts nothing on its own. A form that opts in (a renderer’s /form wrapper, enhanceDropletForm of $droplets/form, or data-droplet-enhance on the form, which /index.js binds for any droplet) posts by fetch instead, and only to its own droplet’s action. Enhancing a form has the code for each renderer and what the element does with the result: the re-render, the redirect and the droplets:action event.

A host can put content inside a droplet, and the component decides where it shows (children in each renderer). The host writes its content in one <div data-droplet-slot>, a direct child of the element:

<djs-droplet data-droplet="card">
<!-- … the fragment's own scripts and markup … -->
<div data-droplet-slot>
<p>Anything the host renders, other droplets included.</p>
</div>
</djs-droplet>

A host that fetches fragments on the server appends the container before the closing tag:

const html = await (await fetch(`${DROPLETS}/droplets/card`)).text();
const withChildren = html.replace(/<\/([a-z][\w-]*)>$/, `<div data-droplet-slot>${children}</div></$1>`);
  • The server renders a marker where the component puts children. At connect, before the bundle loads, the element moves the container into it, so the children show at once.
  • When there is no marker (the component hides its children behind a false if, or is client-only), the container waits under the element, hidden, until the component renders one.
  • When the component renders its children in more than one place, the container lives in the first marker in document order, whichever the component reported first; when that one goes, it moves to the next.
  • The container is moved, never re-created and never taken out of the document: nested droplets, iframes and form state among the children survive hydration, re-renders, the switch to the error page and dev remounts (with moveBefore where the browser has it).
  • The element’s direct children are exactly the payload scripts, the droplet’s stylesheet link (and the preloads the element adds with it), the content root (data-droplet-entry) and that container. Anything else directly under the element is removed at connect, with a warning in dev.

A page with no server of its own (a single-page app, a static page) can write the element directly. Without server markup, the droplet mounts in the browser:

<script type="module" src="https://drops.example.com/index.js"></script>
<djs-droplet data-droplet="hello" data-droplet-props='{"who":"Ana"}'></djs-droplet>
Attribute Meaning
data-droplet The droplet id.
data-droplet-props Plain JSON props. host in server loads is then the page’s own.
data-droplet-context Base64 JSON { host, props }, as a fragment carries it when it has no inline context.
data-droplet-hydrate Overrides the droplet’s hydrate mode.

The props come from the first of these that parses: a fragment’s inline context script, then data-droplet-context, then data-droplet-props. One that does not parse is logged and the next is read; with none left, the props are {}.

The element loads from where the <script src> points: load /index.js from the droplets server itself, under its prefix if it has one (https://shop.example/mfe/index.js), or from a CDN that pulls it from the server at the same URL. location in the config fixes the URLs the server writes, not this: the browser bundles always take the location from the URL of /index.js.

The element runs the props schema and +droplet.ts in the browser, requests _data when the droplet has a server load, links the droplet’s stylesheet inside itself (Styles), and mounts with data as a promise once the stylesheet is in.

Each droplets server defines its own element, named by its element option, and its elements load from where its own /index.js came from. A page can embed droplets from as many servers as it likes, as long as each has a distinct element: with the default name, the second server’s index.js finds <djs-droplet> already defined and its droplets stay inert.