Deployment
The build
Section titled “The build”vite builddist/ client/ droplets.json # manifest: build hash, entry, global CSS, per-droplet bundle and stylesheets index.js # /index.js: imports env.js (with runtime public variables) and assets/index.<hash>.js index.css # /index.css: imports the shared stylesheet under assets/, for a page that links it itself droplets/<id>/client.js # one bundle per droplet that hydrates droplets/<id>/style.css # what /droplets/<id>/style.css answers, for a droplet with stylesheets assets/ # entry client (index.<hash>.js), stylesheets, shared chunks, imported files assets/public/ # a copy of public/, served at /assets/public/* server/entry-server.js # the SSR renderer server/_prerendered/ # build-time renders, for droplets with prerender = true; never served server.js # the HTTP server, with droplets.config.ts baked invite build empties dist/ first, by Vite’s own rule (build.emptyOutDir:
always when true, never when false, else only when it is inside the
project), so nothing of a build with another adapter stays next to the new
one. That is the layout of node(), bun() and deno(); ship the whole dist/
folder. cloudflare() writes dist/worker.js instead of dist/server.js
and dist/server/, and keeps the prerendered renders in dist/client
(Cloudflare Workers). /env.js is not a file: the
server answers it.
dist/server.js bundles the framework’s own dependencies (Hono, your
renderers’ server runtimes). What stays external is whatever your droplets and your config
import from node_modules. A project whose droplets import nothing beyond
their framework produces a dist/ that runs with no node_modules at all.
Adapters
Section titled “Adapters”The runtime, the routes, the renderer and the element contract use web APIs
only (Request, Response, fetch, TextEncoder, atob), so they run on
any JavaScript runtime. What differs per runtime is the thin entry around
them: how the SSR bundle is loaded, how the client build is read, how the
process listens. An adapter supplies that entry, SvelteKit-style, and is
required for vite build:
import { droplets } from "@dropletsjs/droplets/vite";import { svelte } from "@dropletsjs/renderer-svelte";import { node } from "@dropletsjs/adapter-node";
export default defineConfig({ plugins: [droplets({ adapter: node(), renderers: [svelte()] })] });| Adapter | Package | Emits |
|---|---|---|
node() |
@dropletsjs/adapter-node |
dist/server.js + dist/server/entry-server.js; reads dist/client and dist/server/_prerendered from disk, serves only /assets/ as files (public/ at /assets/public/). vite preview uses it too. |
cloudflare() |
@dropletsjs/adapter-cloudflare |
dist/worker.js, self-contained, renderer and manifest inlined; dist/client served by Workers Static Assets. |
bun() |
@dropletsjs/adapter-bun |
As node(); bun dist/server.js serves it. |
deno() |
@dropletsjs/adapter-deno |
As node(); deno serve -A dist/server.js serves it. |
An adapter is a small object (DropletsAdapter in @dropletsjs/droplets):
the server entry to bundle, the output file name, whether the SSR renderer is
emitted separately, noExternal patterns or true to bundle everything,
extra Vite environment options, an afterBuild hook and an optional
preview. The entry itself calls createServerApp({ ssr, assets, config })
with loaders for its platform, and gets the config, the renderer and the
manifest through virtual:droplets-config, virtual:droplets-ssr and
virtual:droplets-manifest. The shipped adapters are the reference:
packages/adapters/node and packages/adapters/cloudflare in the repository;
bun and deno only change how node’s app is served. Prerendered renders
are server-only: an adapter with separateSsrBundle reads them from
dist/server/_prerendered/; one without finds them in the client build under
the manifest’s __prerendered, a directory named anew every build, and must
keep the manifest itself private. createPrerenderedLoader(read) takes a
read rooted at that directory.
Cloudflare Workers
Section titled “Cloudflare Workers”pnpm add -D @dropletsjs/adapter-cloudflare wranglerimport { cloudflare } from "@dropletsjs/adapter-cloudflare";export default defineConfig({ plugins: [droplets({ adapter: cloudflare(), renderers: [svelte()] })] });{ "name": "my-droplets", "main": "dist/worker.js", "compatibility_date": "2025-10-01", // AsyncLocalStorage, which keeps overlapping requests apart. "compatibility_flags": ["nodejs_compat"], "assets": { "directory": "dist/client", "binding": "ASSETS" }}vite buildwrangler dev # local, in workerdwrangler deploycloudflare({ assetsBinding }) names the assets binding when it is not
ASSETS; the name is fixed in dist/worker.js at build. Without
nodejs_compat the Worker has no AsyncLocalStorage, and requests that
overlap share one request store: vite build warns once when the wrangler
config’s compatibility_flags lacks it, and never fails. There is no vite preview for Workers
(it warns and serves nothing): wrangler dev is the preview. With
location set, the URLs the
Worker writes under wrangler dev point at that location.
Static files and _headers
Section titled “Static files and _headers”Workers Static Assets answer every request for a file in dist/client
before the Worker runs: /index.js, /index.css, the entry and the chunks under
/assets/*, public/ under /assets/public/*, and each droplet’s
/droplets/<id>/client.js and /droplets/<id>/style.css. Those requests
are not Worker invocations, so they are not billed as such. Everything else
reaches the Worker: renders at /droplets/<id>, /droplets/<id>/_data,
actions, /env.js, /api/* and the health check.
vite build writes dist/client/_headers, which gives those files their
headers:
/index.js Access-Control-Allow-Origin: * X-Content-Type-Options: nosniff ! Cache-Control Cache-Control: no-store/index.css Access-Control-Allow-Origin: * X-Content-Type-Options: nosniff ! Cache-Control Cache-Control: no-store/assets/* Access-Control-Allow-Origin: * X-Content-Type-Options: nosniff ! Cache-Control Cache-Control: public, max-age=2592000, immutable/assets/public/* ! Cache-Control Cache-Control: no-cache/droplets/:id/client.js Access-Control-Allow-Origin: * X-Content-Type-Options: nosniff ! Cache-Control Cache-Control: public, max-age=2592000, immutable/droplets/:id/style.css Access-Control-Allow-Origin: * X-Content-Type-Options: nosniff ! Cache-Control Cache-Control: public, max-age=2592000, immutableThe /assets/public/* rule carries
publicCacheControl (no-cache by default); with
publicCacheControl: false it keeps only ! Cache-Control. These files are
public, so they are sent with Access-Control-Allow-Origin: * whatever
cors says; cors applies to what the Worker answers. Every file is sent
with X-Content-Type-Options: nosniff, as the Node adapter sends it, so a
browser takes it for what its Content-Type says and nothing else. Cloudflare reads
_headers and never serves it as a file
(Headers),
so .assetsignore does not list it.
To add your own rules, put a _headers file in the project root (next to
wrangler.jsonc, not in public/). vite build appends it after the
adapter’s rules. Cloudflare applies every rule that matches a path and joins
a header that two rules set with a comma, so a rule that changes
Cache-Control starts with ! Cache-Control:
/assets/public/fonts/* ! Cache-Control Cache-Control: public, max-age=31536000A public/_headers lands at /assets/public/_headers, where Cloudflare
never reads it, and the build warns once. The build also warns when the
file has more than 100 rules or a line longer than 2,000 characters,
Cloudflare’s limits.
run_worker_first
Section titled “run_worker_first”Leave run_worker_first out. The build’s files need nothing from the
Worker: /index.js and /index.css are files of the build and _headers
carries their CORS and cache headers.
true, or a list whose patterns match /index.js, /index.css, /assets/* or a
droplet’s client.js or style.css, sends those requests through the
Worker, billed per request. The adapter reads your wrangler config
(wrangler.jsonc, wrangler.json or wrangler.toml) after vite build
and warns once when it does, naming the paths it matched; a ! pattern
that excludes a path wins. The build goes on: the setting is yours. A list
that matches none of them (["/api/*"]) is silent, and so is false. It
also warns when the file does not parse.
The Worker bundles everything, so there are no node_modules at runtime.
PORT and server.port do not apply. Environment variables come from the
Worker’s bindings, and platform.env in server code holds them all.
Prerendered droplets are read through the assets binding, from
dist/client/_prerendered/<random>/: a name new every build that only the
Worker’s inlined manifest holds, so no assets config makes them reachable at
a URL one could guess. public/ is in dist/client/assets/public/, served at
/assets/public/* with publicCacheControl and the static assets’ ETag. A
file under /assets/ that is missing answers 404 with no-store; nothing
else of dist/client is a route (/robots.txt is a 404). vite build
also writes dist/client/.assetsignore, which keeps droplets.json and
.vite/ out of the upload. Set cors in droplets.config.ts if pages on
other origins embed your droplets: it applies to what the Worker answers
(fragments, _data, /env.js, /api/*). With no wrangler config at all,
the build logs what to set: main, assets.directory and
assets.binding.
Plain Node
Section titled “Plain Node”PORT=8000 node dist/server.jsPORT overrides server.port from the config (default 8000), read once
at startup. It listens on every interface and logs nothing on start: it logs
errors only, to stderr; see Logging. The server finds client/
and server/ next to its own file, whatever the working directory, and
reads dist/client/droplets.json on the first request and keeps it once it
has loaded; while it is missing or not valid JSON, the server logs that once
and reads the file again on the next request, so a build that finishes after
it started is picked up without a restart.
Importing dist/server.js instead of running it does not start listening.
Its default export is { fetch }, a standard Request => Promise<Response>
handler, and runServer() starts listening on demand. node dist/server.js
listens, as does node dist/server without the extension or a symlink to
the file.
PORT=8000 bun dist/server.jsThe default export is { port, development: false, fetch }, and Bun serves
it when the file is the entry point, logging
Started server: http://localhost:<port>. port is server.port, with
PORT over it, as on Node. development: false keeps Bun’s debug page
away: an error answers with the droplet’s error page. Imported, it hands
over fetch and does not listen. Bun 1.2 or newer.
deno serve -A --port 8000 dist/server.jsdeno serve serves the default export { fetch } and owns the port: --port
(8000 by default) rather than PORT or server.port. --parallel runs one
worker per CPU core. -A grants what the server needs: reading dist/, the
environment for $droplets/env/private, and the network. Packages your
droplets import come from node_modules, as with Node: deno install puts
them there for a project with a package.json. Deno 2 or newer.
Docker
Section titled “Docker”A build stage that runs vite build, and a runtime stage that copies only
dist/:
FROM node:24-alpine AS buildWORKDIR /appCOPY package.json pnpm-lock.yaml ./RUN npm install -g pnpm && pnpm install --frozen-lockfileCOPY . .RUN pnpm build
FROM node:24-alpineWORKDIR /appENV NODE_ENV=productionENV PORT=8000COPY --from=build /app/dist ./distEXPOSE 8000USER nodeCMD ["node", "dist/server.js"]If your droplets import packages that are not bundled, also copy
node_modules (or run pnpm install --prod in the runtime stage). The
repository’s examples/frameworks/Dockerfile is the same thing for a
workspace package (--build-arg EXAMPLE=vue picks the example); the
host examples run against the image it builds.
Inside another server
Section titled “Inside another server”Because dist/server.js exports a fetch handler, any Node server can mount
it. With Express and @hono/node-server:
import express from "express";import { getRequestListener } from "@hono/node-server";
const droplets = (await import("./dist/server.js")).default;const app = express();
app.get("/", (req, res) => res.send("my page"));app.use(getRequestListener(droplets.fetch)); // /index.js, /droplets/*, /assets/*, /api/*
app.listen(3000);Droplet routes and your routes then share one origin: no CORS, no
x-droplet-location, and the page can call
droplets.fetch(new Request(url)) in-process to render fragments without an
HTTP round trip. The
Express example shows both this and the usual
separate-process setup.
Behind a proxy
Section titled “Behind a proxy”When a reverse proxy fronts the droplets server:
- forward
/index.js,/env.js,/index.css,/droplets/*and/assets/*to it (and/api/*if you use it,/importmapand/importmap.jswith an import map); - set
x-droplet-locationto the public URL, written out in the proxy’s configuration (never built from the request’sHost, and overwriting anyx-droplet-locationa client sent), so fragments point at the proxy. Under a path, include it:x-droplet-location: https://shop.example/mfe. List its origin intrustedOrigins(orDROPLETS_TRUSTED_ORIGINS): the server ignores a location whose origin is not its own or listed there. A proxy that already sendsForwardedorX-Forwarded-ProtoandX-Forwarded-Host(withX-Forwarded-Prefixunder a path) is read the same way, whenx-droplet-locationis absent. Withlocationset, skip this: the server reads none of these headers and writes every URL onlocation, so a proxy under another origin or prefix gets URLs that point elsewhere. Keep the droplets server unreachable except through the proxy; - the
securedefault of a cookie is judged by the droplet location, not by the socket: a server reached over plain HTTP on a loopback address sends cookies withoutSecureunless its location sayshttps. Behind a TLS proxy that forwards to plain HTTP onlocalhost, setlocationor send a trusted location header, sohttps://is the location and the cookies areSecure; - keep the
cache-controlheaders it sends; they are safe to honor:/index.jsand/index.cssareno-store,/env.jsispublic, max-age=600(DROPLETS_ENV_MAX_AGE), fragments and_dataareprivate, no-store, no-transform(fragmentCacheControl, withno-transformalways added),/assets/public/*isno-cache(publicCacheControl) with anETag, everything else it serves for the browser is immutable.
What a page loads through the proxy, and what handle sees of it:
HTML rewriters and no-transform
Section titled “HTML rewriters and no-transform”Some proxies rewrite the HTML they pass on: Cloudflare’s Web Analytics
(automatic setup) and Email Address Obfuscation, its JavaScript detections,
mod_pagespeed. A fragment has no </body>, so a script such a feature
appends lands after the droplet’s element, and a host that inlines the
fragment inlines it too; the browser’s re-render after an enhanced form
gets it as well. So every fragment and _data answer carries
Cache-Control: no-transform, which turns these rewrites off. The
framework adds it to whatever Cache-Control the answer has (the
fragmentCacheControl default, your own value, a load’s setHeaders,
handle’s, an error answer’s); it is never sent twice.
A proxy that honors no-transform stops compressing those answers too
(Cloudflare does), so the droplets server gzips them itself for a client
that asks for gzip, with Vary: Accept-Encoding (see
Compression). The files under
/assets/, /index.js, /index.css and /env.js keep their
Cache-Control and are compressed by the CDN as before. A Worker passes
the gzipped body on as it is.
/index.js and CDNs
Section titled “/index.js and CDNs”The elements load from where the page loaded /index.js, prefix included:
it records its own URL. So /index.js must come from the droplets
server, under its prefix: https://shop.example/mfe/index.js makes the
elements load from https://shop.example/mfe. A CDN in front works when it
pulls from the server at the same URL (origin pull); /index.js is
no-store, /assets/public/* revalidates, the rest is immutable and caches well. Copying the files to
another bucket under another URL works only with
location set to that URL: the
server then writes every fragment’s URLs there.
Trusted origins at runtime
Section titled “Trusted origins at runtime”DROPLETS_TRUSTED_ORIGINS (comma-separated origins) adds to trustedOrigins
from the config, read at runtime on every adapter (a Worker’s binding, the
process environment on Node, Bun and Deno). One build can then trust
different hosts per deployment. An entry that is not an origin is skipped
(with a warning under vite dev).
DROPLETS_SECRET
Section titled “DROPLETS_SECRET”Forms posted without JavaScript are answered with a redirect back to the
host page, the action’s result signed in its URL
(Post/Redirect/Get).
Set DROPLETS_SECRET to 32 or more random bytes (openssl rand -base64 48),
the same on every instance serving a build, as a secret: a Worker secret, the
process environment elsewhere. It is read at runtime and never reaches a
browser bundle. Without it such a post answers the droplet’s fragment
instead (vite dev says so once). Rotating it voids the results minted in
the last five minutes, nothing else.
On Workers, the first deploy creates the Worker with its secret, from a
temporary JSON file: a wrangler secret put before the Worker exists
creates an empty Worker of that name. Later deploys keep it; secret put
rotates it.
vite buildtmp=$(mktemp)printf '{"DROPLETS_SECRET":"%s"}\n' "$(openssl rand -base64 48)" > "$tmp"wrangler deploy --secrets-file "$tmp"rm "$tmp"
openssl rand -base64 48 | wrangler secret put DROPLETS_SECRET # a rotationA host that fetches fragments on its server can pass their
Link header on with its page, so
the browser starts on the stylesheets, the entry and the bundles early.
See the nginx example for a complete configuration, and Security model for what the droplets server trusts.
Health and readiness
Section titled “Health and readiness”GET /health (the health option) answers ok with status 200 as soon as
the server is listening, before handle runs. The SSR bundle is loaded on the
first request that needs it.
Logging
Section titled “Logging”A production server logs errors only, with console.error: a message, then
the error itself, nothing else. Those are:
- a droplet’s load failed (
<droplet>: droplet load failed); - a form action failed;
- an action’s
redirect()points off this server and its trusted origins, answered400; - a request failed (
<where> failed: <path>, such asdroplet failed: /droplets/cart); handleErrorinhooks.server.tsfailed, or could not be loaded;- on Node, Bun and Deno,
dist/client/droplets.jsonis missing (not built) or not valid JSON (the build did not finish), once per failure.
Warnings are for vite dev and vite build, and never reach a production
bundle: an untrusted forwarded location, "*" in trustedOrigins, an
entry of DROPLETS_TRUSTED_ORIGINS that is not an origin,
DROPLETS_SECRET missing or too short, cors allowing
every origin, a malformed x-droplet-props, an action result over 2 KB. Set
their level with DEV_DROPLETS_LOG (error, warn, info, the default,
or debug); a production server ignores it.
What / serves
Section titled “What / serves”In production and vite preview, / serves the index page: the file the
option names, else index.html in the project root, else a small placeholder.
It is served as written, not processed by Vite. index: false answers 404.