Skip to content

Deployment

Terminal window
vite build
dist/
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 in

vite 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.

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:

vite.config.ts
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.

Terminal window
pnpm add -D @dropletsjs/adapter-cloudflare wrangler
import { cloudflare } from "@dropletsjs/adapter-cloudflare";
export default defineConfig({ plugins: [droplets({ adapter: cloudflare(), renderers: [svelte()] })] });
wrangler.jsonc
{
"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"
}
}
Terminal window
vite build
wrangler dev # local, in workerd
wrangler deploy

cloudflare({ 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.

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, immutable

The /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=31536000

A 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.

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.

Terminal window
PORT=8000 node dist/server.js

PORT 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.

Terminal window
PORT=8000 bun dist/server.js

The 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.

Terminal window
deno serve -A --port 8000 dist/server.js

deno 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.

A build stage that runs vite build, and a runtime stage that copies only dist/:

FROM node:24-alpine AS build
WORKDIR /app
COPY package.json pnpm-lock.yaml ./
RUN npm install -g pnpm && pnpm install --frozen-lockfile
COPY . .
RUN pnpm build
FROM node:24-alpine
WORKDIR /app
ENV NODE_ENV=production
ENV PORT=8000
COPY --from=build /app/dist ./dist
EXPOSE 8000
USER node
CMD ["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.

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.

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, /importmap and /importmap.js with an import map);
  • set x-droplet-location to the public URL, written out in the proxy’s configuration (never built from the request’s Host, and overwriting any x-droplet-location a client sent), so fragments point at the proxy. Under a path, include it: x-droplet-location: https://shop.example/mfe. List its origin in trustedOrigins (or DROPLETS_TRUSTED_ORIGINS): the server ignores a location whose origin is not its own or listed there. A proxy that already sends Forwarded or X-Forwarded-Proto and X-Forwarded-Host (with X-Forwarded-Prefix under a path) is read the same way, when x-droplet-location is absent. With location set, skip this: the server reads none of these headers and writes every URL on location, so a proxy under another origin or prefix gets URLs that point elsewhere. Keep the droplets server unreachable except through the proxy;
  • the secure default 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 without Secure unless its location says https. Behind a TLS proxy that forwards to plain HTTP on localhost, set location or send a trusted location header, so https:// is the location and the cookies are Secure;
  • keep the cache-control headers it sends; they are safe to honor: /index.js and /index.css are no-store, /env.js is public, max-age=600 (DROPLETS_ENV_MAX_AGE), fragments and _data are private, no-store, no-transform (fragmentCacheControl, with no-transform always added), /assets/public/* is no-cache (publicCacheControl) with an ETag, everything else it serves for the browser is immutable.

What a page loads through the proxy, and what handle sees of it:

What a page loads, and how it is cachedThe host page has one module script, <location>/index.js, and, when it links the shared stylesheet itself, <location>/index.css. /index.css is no-store and exists only with a shared stylesheet: it @imports /assets/droplets-css-<hash>.css, immutable, the stylesheet every droplet shares. /index.js is no-store: it names this build's entry. It imports /env.js, public with max-age=600 and only there when public variables are read at runtime, and /assets/index.<hash>.js, immutable, which defines the element. These are files of the build: handle never runs for them, nor cookies. Then each element asks its droplet's routes, which go through handle: style.css?c=<build>, immutable, when the droplet has styles; client.js?c=<build>, immutable, only when it hydrates; and _data, a POST answered private, no-store, only when nothing came inline.The host page<script type="module" src="<location>/index.js"><link rel="stylesheet" href="<location>/index.css">Files of the build: no handle, no cookies/index.cssno-store; only with a shared stylesheet,for a page that links it@import/assets/droplets-css-<hash>.cssimmutable; the stylesheet every dropletshares/index.jsno-store: it names this build's entryimports/env.jspublic, max-age=600; only with publicvariables read at runtime/assets/index.<hash>.jsimmutable; defines the elementGET, when linkedGETeach elementRoutes of the droplet, /droplets/<id>/…: through handlestyle.css?c=<build>immutable; when thedroplet has stylesclient.js?c=<build>immutable; only when ithydrates_dataPOST, private, no-store;only when nothing cameinlineWhat a page loads, and how it is cachedThe host page has one module script, <location>/index.js, and, when it links the shared stylesheet itself, <location>/index.css. /index.css is no-store and exists only with a shared stylesheet: it @imports /assets/droplets-css-<hash>.css, immutable, the stylesheet every droplet shares. /index.js is no-store: it names this build's entry. It imports /env.js, public with max-age=600 and only there when public variables are read at runtime, and /assets/index.<hash>.js, immutable, which defines the element. These are files of the build: handle never runs for them, nor cookies. Then each element asks its droplet's routes, which go through handle: style.css?c=<build>, immutable, when the droplet has styles; client.js?c=<build>, immutable, only when it hydrates; and _data, a POST answered private, no-store, only when nothing came inline.The host page<script type="module"src="<location>/index.js"><link rel="stylesheet"href="<location>/index.css">Files of the build:no handle, no cookies/index.cssno-store; only with a shared stylesheet, for apage that links it@import/assets/droplets-css-<hash>.cssimmutable; the stylesheet every dropletshares/index.jsno-store: it names this build's entryimports/env.jspublic, max-age=600; only with public variablesread at runtime/assets/index.<hash>.jsimmutable; defines the elementGET, when linkedGETeach elementRoutes of the droplet,/droplets/<id>/…: through handlestyle.css?c=<build>immutable; when the droplet has stylesclient.js?c=<build>immutable; only when it hydrates_dataPOST, private, no-store; only when nothingcame inline
Two no-store files name the build; everything they lead to is immutable or briefly cached, and only the droplet's routes reach handle.

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.

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.

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).

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.

Terminal window
vite build
tmp=$(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 rotation

A 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.

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.

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, answered 400;
  • a request failed (<where> failed: <path>, such as droplet failed: /droplets/cart);
  • handleError in hooks.server.ts failed, or could not be loaded;
  • on Node, Bun and Deno, dist/client/droplets.json is 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.

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.