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.
src/hooks.client.ts
Section titled “src/hooks.client.ts”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.
import type { ClientInit } from "@dropletsjs/droplets";import { MessageQueue } from "./lib/message-queue.ts";
export const init: ClientInit = () => { window.shopMessageQueue ??= new MessageQueue();};/index.jscallsinit()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.jscalls 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 owninit. - It is browser code: importing a server file (
*.server.*, a file under aserver/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, sinceinitruns once per page. Withdev.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.
What happens on connect
Section titled “What happens on connect”From the script tag to a live droplet:
When a droplet element connects to the page, it:
- takes where to load from: the URL
/index.jswas loaded from, path prefix included (before/index.jsrecorded it, the root of the build its bundle came from, prefix included). The markup has no say in it; - links the droplet’s stylesheet inside the element when the markup did not bring it (see Styles);
- moves the host’s children into place (see Host children);
- 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
Server HTML: the buttons wake up once React hydrates.
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.
Styles
Section titled “Styles”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.
Lazy hydration
Section titled “Lazy hydration”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.
Clicks before hydration
Section titled “Clicks before hydration”Between the server markup appearing and the bundle hydrating it, a click would hit dead HTML. The element holds them instead:
- every
clickon 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.
Host children
Section titled “Host children”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
moveBeforewhere 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.
Elements a host writes itself
Section titled “Elements a host writes itself”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.
Several servers on one page
Section titled “Several servers on one page”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.