Development
The dev server
Section titled “The dev server”vite dev runs the droplet routes as middleware inside Vite’s own server,
after Vite’s own, and needs no adapter. Modules are transformed on demand;
handle, +server.ts routes and handleError are read again per request,
so edits appear without a restart, including adding or deleting a droplet
folder or an API route. Changing droplets.config.ts, src/env.ts, or
anything they import, restarts the server. Runtime variables come from the
.env files, as in Vite. The port is Vite’s server.port, else
dev.server.port of droplets.config.ts (5173); PORT belongs to the
production server and does not move vite dev.
What differs from a build:
locationandhostof the config are ignored: the location comes from each request (a trusted header, else the dev server’s own origin), andevent.hostfrom the request too. A prerender entry without its ownhostis host-agnostic.- Nothing is prerendered: listed
entriesprops render live. - Droplets have no
style.cssof their own (it answers404, fragments link none) and fragments send noLinkheader: Vite injects the styles (see Known limitations). /index.jsis generated per request, with the hot-update client in it.
A droplet whose files fail to import, a component that imports
$droplets/server, a load file with a syntax error, fails alone: its
fragment answers 500 and the browser’s import of its component is refused,
with the import chain in the terminal, while every other droplet, their
client.js and /index.js keep answering. Each droplet’s modules are
imported when it is first asked for, so the next request after the fix tries
again, with no restart. A build fails as a whole, naming the chain.
vite preview serves the production build through the adapter’s preview:
Node, Bun and Deno run the Node adapter’s app over dist/, with the routes
node dist/server.js would expose. Cloudflare has no preview (vite preview
warns and serves nothing): run wrangler dev after vite build. A build
with location set writes its
URLs on that location under preview too, so a page under preview loads its
files from there.
The dev log
Section titled “The dev log”vite dev and vite build print what the framework notices, prefixed
[droplets:framework]: a droplet folder that is not lowercase kebab-case, a
flag that is not a literal, flags an error page declares (in dev), an untrusted
location header, "*" in trustedOrigins, a missing DROPLETS_SECRET, a
malformed x-droplet-props. DEV_DROPLETS_LOG sets the level: error,
warn, info (the default) or debug. None of it reaches a production
bundle; a production server logs errors only
(Logging).
The devtools page
Section titled “The devtools page”pnpm add -D @dropletsjs/devtoolsimport { dropletsDevtools } from "@dropletsjs/devtools";
export default defineConfig({ plugins: [droplets({ adapter: node(), renderers: [svelte()] }), dropletsDevtools()],});With it, / in vite dev is a page for working on one droplet at a time. The
droplet gets the whole viewport; a panel floats above it, can be dragged or
folded into a pill (Alt+D), and remembers where it was. Pick a droplet, edit
its props with a builder or as JSON, send them by GET or POST, and see its
flags, renderer and files. The page re-renders when the droplet or the
registry changes, and shows error pages as they are.
- Client mode (
/): the browser fetches the fragment and inserts it. - Server mode (
/?droplet=<id>&props=<json>&method=GET|POST): the page arrives with the droplet already in it, as from a host that renders on the server.
The devtools never run in vite build or vite preview; nothing of them
reaches a build.
Hot updates
Section titled “Hot updates”When a file a droplet depends on changes, the plugin tells every page that shows the droplet, over Vite’s socket. A shared file (a component several droplets import) reaches every droplet above it in the module graph.
This works on any page that loads index.js from the dev server, not
only the devtools page. A droplet embedded in your Rails app and served from
localhost:5173 updates in place while you edit it. The host’s page is
yours, not the dev server’s, so no strategy but "reload" ever reloads it.
What happens on an edit depends on dev.strategy:
| Strategy | On a change |
|---|---|
"hmr" (default) |
The framework’s own HMR, which keeps component state where it can. Load edits arrive as new data, and render-contract changes arrive as a notice. See the table below. |
"remount" |
The droplet loads again, by its flags as they are now, the way it reached the page. A server fragment is requested again with the same context and hydrates, or stays as the server rendered it when hydrate = false (under vite dev that fragment keeps its context for this; a production one has none). An element the host wrote, or a clientOnly fragment, mounts in the browser. The host’s children are carried over. State starts over. |
"reload" |
The page reloads, so a host that renders on the server renders again. |
"manual" |
Nothing; the console says which droplet changed. |
A page can override the strategy on its script tag, for that page only:
<script type="module" src="http://localhost:5173/index.js?strategy=remount"></script>Only index.js reads these parameters; fragments and the other routes are
unchanged.
What hmr does
Section titled “What hmr does”Stylesheets (imported CSS, CSS modules, the shared stylesheet) update live
through Vite’s own CSS updates, with nothing remounted, under every strategy
but "reload". A component’s own styles follow its framework’s HMR.
A component edit, in the component or in anything it imports:
| Renderer | What happens | State |
|---|---|---|
| React | Fast Refresh | kept |
| Preact | Prefresh | kept |
| Vue | @vitejs/plugin-vue HMR. A template edit re-renders; a <script> edit reloads the component. |
kept for a template edit; starts over for a script edit |
| Svelte 5 | @sveltejs/vite-plugin-svelte HMR swaps the component in place |
starts over |
| Solid | solid-refresh swaps the component in place | starts over |
| Lit, Hono JSX | No HMR of their own. The droplet remounts in place, as under "remount". |
starts over |
| Handlebars | Not hydrated: the fragment is requested again and the markup swapped. Hydrated: the droplet remounts in place, as under "remount" |
none to keep |
| Script | The previous cleanup runs, then the new default(data, el) runs on the same el |
yours |
If no HMR of the framework takes an edit (React Fast Refresh, for example,
gives up on a module that also exports a non-component), the droplet remounts
in place, and the console says so. A droplet whose markup does not hydrate
(hydrate = false, or not hydrated yet) gets the server’s new markup.
A load edit (+droplet.server.ts, +droplet.ts, or a module only they
import): the loads run again, through _data as on any render, and the live
component receives the new data without a remount. Its state is kept. A
Vue component whose setup awaits props.data remounts instead, and a
script droplet runs its cleanup and its function again.
A render-contract change (ssr, hydrate or prerender in the
droplet’s flags) leaves the droplet on the page as it is. A notice names the
droplet and the change, for example counter changed its render contract:
hydrate true → false:
| Change | What happens |
|---|---|
ssr false → true |
A notice with Reload page. The host has to ask for the fragment again to get the server’s markup. |
ssr true → false |
A notice. |
hydrate false → true, "visible" or "interactive" |
The droplet hydrates live, in the new mode, and a notice says so. |
hydrate on → false |
A notice with Reload page. The running component stays live until then. |
hydrate between modes |
Not hydrated yet: the droplet waits in the new mode. Already hydrated: a console line only. |
prerender, either way |
A notice. Prerendering happens in vite build, so check it with vite preview. |
An edit to src/hooks.client.ts gets a notice with Reload page as well:
init() runs once per page, before any droplet.
Notices show in the dev tool when it is on the page.
Otherwise they show as a small toast in the corner of the page, in its own
shadow root, out of the host’s styles. A notice with a button is an alert
dialog. One without is a status that closes after ten seconds. Every notice
can be dismissed with its × button, or with Escape while it has focus. A
newer notice about the same flags of the same droplet replaces the older
one, and no more than three show at once. Each notice also writes one line
to the console. None of this exists outside vite dev; nothing of it
reaches a build.
The dev tool
Section titled “The dev tool”The dev tool is a floating panel for pages that embed droplets: your host
pages, not only the devtools page. Turn it on for every page with
dev.injectTool: true, or for one page:
<script type="module" src="http://localhost:5173/index.js?injectTool=true"></script>(?injectTool=false turns it off for that page.) The devtools page always has
it. It needs dropletsDevtools() in the Vite config; without it,
injectTool warns in the console.
- One panel per page,
window.DropletsDevTools, in a shadow root. A page that embeds droplets from several dev servers gets one group per server. - Each group lists that server’s droplets on the page in document order, with
their mode (flags and
data-droplet-hydrate), renderer and state: waiting, loading, hydrated, mounted, error, static, empty. Hovering one outlines it on the page; its name scrolls to it. - The strategy can be switched per server for the tab’s session. Under
manual, a changed droplet is marked, and Remount or Reload page load it again. - Notices of
hmr(a new render contract, ahooks.client.tsedit) show at the bottom left of the page, under the panel’s styles.
Workspace development
Section titled “Workspace development”In the droplets repository itself, the example imports the packages’ compiled
dist/:
pnpm installpnpm build # compile every packagepnpm dev # the Svelte example on :5173pnpm dev:lib # in a second terminal: rebuild dist/ on savepnpm check # biome, build, typecheck, integration tests, the examples, the demoKnown limitations
Section titled “Known limitations”Other origins in dev. A host page on another origin can load droplets from
vite dev; Vite’s dev server allows localhost and 127.0.0.1 origins by
default. A host on another hostname needs server.cors in vite.config.ts
(and cors in droplets.config.ts, as in production). Name the host rather
than allowing every origin: server.cors: true lets any site you visit read
the dev server’s sources while it runs.
export default defineConfig({ server: { cors: { origin: ["http://shop.local:8080"] } }, plugins: [droplets({ renderers: [svelte()] })],});Files in dev. Imported files and CSS url()s are on the dev server
itself, absolute (http://localhost:5173/src/lib/logo.png): the plugin sets
Vite’s server.origin to the dev server’s address unless you set one, so a
host page on another origin loads them. They ignore a location’s path prefix:
vite dev serves its modules from its root, so try a prefixed proxy against a
build (vite preview). Stylesheets
are not linked inside the element as in a build: Vite injects them into the
host page’s <head> as <style> elements. public/ is served at
/assets/public/* as in a build, and Vite also serves it at the root
(/robots.txt), which a build does not.
Scoped styles of non-hydrating droplets in dev. In dev, a component’s
styles reach the browser through the droplet’s client module. A droplet with
hydrate = false never loads that module, so it renders without its component
styles in dev, and with them in a build. The shared stylesheet, Tailwind
included, is unaffected: Vite injects it with /index.js. See Styling.
Flags are read before compiling. They must be literals in the component; see Flags.
State across a component edit. Under hmr, React and Preact keep hook
state, and Vue keeps it for a template edit. Svelte 5, Solid, Lit and Hono JSX
start the component over: their HMR, or the remount, creates a new instance.
The data stays the same either way.
Load edits in Vue and Solid. A Vue component whose setup awaits
props.data remounts on a load edit, so its state starts over. New data
reaches a Solid component through its props, so only a component that reads
props.data where Solid tracks it (in JSX, a memo) shows it. A component
that reads it once at setup keeps the old data until its next edit.
prerender in dev. vite dev renders every request, so a change to
prerender shows only in a build: check it with vite preview.
The devtools page under hmr. The page leaves an edit to the droplet it
shows. The droplet’s own HMR updates it, and the page itself does not render
again.
Remounting a noSSR fragment. A host’s ?noSSR request cannot be told
apart from ssr = false; on a remount the fragment is requested without it.