The HTTP contract
A droplets server is an ordinary HTTP server. These routes are the whole interface; anything that can make a request can host a droplet.
Routes
Section titled “Routes”| Route | Returns |
|---|---|
GET /droplets/:id |
The droplet as an HTML fragment, props from the query string (or x-droplet-props) |
POST /droplets/:id |
With a JSON body: the same fragment, props from { "host": "…", "props": { … } } (host optional: the page the droplet renders on, for a server-to-server request that has no browser Origin or Referer); the query string is never props here. With a form body: a form action |
GET, POST /droplets/:id/_data |
{ "data": … }: the server load only, no rendering; other methods answer 405 |
GET /droplets/:id/client.js |
That droplet’s bundle; 404 when it never hydrates |
GET /droplets/:id/style.css |
That droplet’s stylesheets, the shared one first, as @imports; 404 when it has none (nothing links to it then) |
GET /index.js |
A small file of the build, no-store, that imports the entry client, which defines the droplet element, and /env.js when there are dynamic public variables |
GET /env.js |
The public variables read at runtime, as a script /index.js imports; public, max-age=600 (DROPLETS_ENV_MAX_AGE); 404 when src/env.ts declares no public variable read at runtime (public: true without static) |
GET /index.css |
A small file of the build, no-store, that imports the shared stylesheet, for pages that link it themselves; 404 when there is none or it is empty |
GET /assets/* |
The entry client, shared chunks, stylesheets and imported files, cached for good |
GET /assets/public/* |
The project’s public/ folder, no-cache (publicCacheControl) with an ETag (304 when If-None-Match matches) |
ALL /api/* |
Your +server.ts endpoints |
GET /health |
ok, for health checks (health option) |
GET /importmap, /importmap.js |
The import map, when there are externals |
GET / |
The index page in production (a placeholder without one, 404 with index: false); the devtools page in vite dev |
Header names follow one rule: what a request sends is singular,
x-droplet-* (x-droplet-location, x-droplet-props); what a response
sends is plural, x-droplets-* (x-droplets-build).
Unknown droplets answer 404, whatever the method: Not Found as text on
the fragment, { "message": "Not Found" } on _data. A known droplet
answers 405 with allow: GET, POST to any other method than GET and
POST (HEAD is a GET without a body), on the fragment and _data
alike, before any body is read. A path no route matches, a trailing slash
included (/droplets/hello/), answers 404 the same way: text, or
{ "message": "Not Found" } under _data and /api. A load that fails
answers the error page with 500 (Errors); error() and
redirect() answer their own status; props the schema refuses answer 400.
Every redirect() a droplets server answers, from a load, transform,
handle, an action or a +server.ts route, carries an absolute location
that is on the server’s own origin, its location’s, a trustedOrigins
entry or host of the config. A
load’s, transform’s, handle’s and an action’s target is resolved
against host (the page); an endpoint’s against the request’s URL on the
location. Any other target, javascript:, a protocol-relative //… or
http(s) with credentials included, answers 400 without a location:
Bad Request: the droplet redirects off this site as text on the fragment,
{ "message": … } on _data and /api (handle and the endpoint name
themselves the same way), with a line in the server log.
Two query flags override the droplet’s flags for one request: ?noSSR skips
rendering but still runs the server load, and ?clientOnly skips both.
The fragment
Section titled “The fragment”GET /droplets/hello?who=Ana answers (formatted here; djs-droplet is the
default tag name):
<djs-droplet data-droplet="hello" data-droplet-build="36a187" data-droplet-render="dfks2s"> <script type="application/text" data-droplet-payload="context">eyJob3N0Ijoi…</script> <script type="application/text" data-droplet-payload="data">eyJkYXRhIjp7…</script> <link rel="stylesheet" href="https://drops.example.com/droplets/hello/style.css?c=36a187" data-droplet-style> <div style="display: contents" data-droplet-entry> <h1>Hello Ana!</h1> </div></djs-droplet>| Part | Meaning |
|---|---|
data-droplet |
The droplet id. |
data-droplet-build |
The build that rendered it; see deploys while a page is open. |
data-droplet-render |
The id of this server render, for engines that key hydration by it. |
data-droplet-error |
Present when the markup is the error page. |
data-droplet-context |
The context as an attribute, when there is no inline data-droplet-payload="context": a fragment without server markup (ssr = false, ?noSSR, ?clientOnly). Absent for droplets that never hydrate. |
data-droplet-payload="context" |
Base64 JSON { host, props }, after the props schema: where it renders, and its props. Sent back when the browser needs _data. Present whenever the fragment has server markup, a prerendered render of an ssr = false droplet included; absent for droplets that never hydrate. |
data-droplet-payload="data" |
Base64 JSON envelope, { "data": … } or { "error": … }. Its presence tells the browser the server load ran. Absent for droplets that never hydrate and for clientOnly. |
link[data-droplet-style] |
The droplet’s style.css, inside the element, ahead of its markup, so the markup never shows unstyled and nothing goes into the host’s <head>. Absent when the droplet has no styles. |
[data-droplet-entry] |
The server-rendered markup. The browser hydrates it in place. |
A droplet with hydrate = false carries its markup alone: no
data-droplet-payload and no data-droplet-context. An enhanced form in it
renders again with the props and page of its action URL.
A host adds its own content as one <div data-droplet-slot> before the closing
tag; see Host children. Hand-written
data-droplet-payload="data" must use the envelope.
Once /index.js has run on the page, every element takes care of itself; see
In the browser. The markup never says where to load
from: the browser loads JavaScript, CSS and data from where /index.js came
from.
The Link header
Section titled “The Link header”Every fragment (GET and POST, live or prerendered,
the error page too) names what the browser will ask for next, as absolute URLs
on the public origin:
Link: <https://drops.example.com/droplets/hello/style.css?c=36a187>; rel=preload; as=style, <https://drops.example.com/assets/Badge-BR92zFkG.css>; rel=preload; as=style, <https://drops.example.com/assets/hello-B1eNVDFs.css>; rel=preload; as=style, <https://drops.example.com/assets/index.C-iXBKI0.js>; rel=modulepreload, <https://drops.example.com/droplets/hello/client.js?c=36a187>; rel=modulepreloadpreloadforstyle.cssand every stylesheet it imports, when the droplet has styles;modulepreloadfor the entry client that/index.jsimports;modulepreloadfor the droplet’s bundle when it hydrates at once (hydrate = true, the default), the error page included, since it hydrates from the same bundle. A droplet that never hydrates, or waits for"visible"or"interactive", gets none.
A host that passes the header on with its own page (or sends it as 103 Early Hints) lets the browser start these downloads before it reaches the element.
Several fragments on one page: join their headers with , . Nothing breaks
when the header is dropped; the downloads start later. vite dev sends
no Link header: there, component styles come with the JavaScript.
style.css
Section titled “style.css”GET /droplets/:id/style.css answers one @import per stylesheet the
droplet needs: those of the components it shares with other droplets first,
then its own. The paths are relative, so they resolve under whatever origin
or path prefix the server is reached through:
@import url("../../assets/Badge-BR92zFkG.css");@import url("../../assets/hello-B1eNVDFs.css");vite build also writes it as a file, dist/client/droplets/<id>/style.css,
so a host that serves the build’s files first (Workers Static Assets)
answers it without the server.
It is served for droplets that never hydrate as well. A droplet without
stylesheets has no file, and the route answers it 404; nothing links to
it then. vite dev answers 404 for every droplet: there, component styles
come with the JavaScript.
GET or POST /droplets/:id/_data runs the props schema and the server load,
and answers { "data": … }, or { "error": … } with a 500 when the load
failed. When host carries a no-JavaScript action’s result for the droplet,
it is { "data": …, "form": … } (Post/Redirect/Get). error() and redirect() answer as they would for the fragment, the redirect’s bound included (400 { "message": … } for a target off this site); the element fetches _data with redirect: "manual", so a redirect reaches it as an opaque answer it logs and renders nothing for.
Every answer carries x-droplets-build, as every fragment answer does,
404 and 405 included. Other methods answer 405.
The two methods are for different callers:
POSTis what the browser sends. Props come from the body’s context only,{ "host": "…", "props": { … } }, with no query string but a cache-buster (__cb); the page’s own query is never forwarded. The browser requests it only for droplets with+droplet.server.ts, only when no data came inline, and never follows a redirect.GETis the public read. Props come from the query string (orx-droplet-props),hostfrom the request’s headers. It is the one to open in a browser, call from a tool or a test, and the one a CDN can cache: a load that is the same for everyone says so withsetHeaders.
export const load = async ({ props, setHeaders }: LoadEvent) => { setHeaders({ "cache-control": "public, max-age=60" }); return { products: await db.products(props.category) };};GET /droplets/products/_data?category=mugs→ 200, cache-control: public, max-age=60 { "data": { "products": [ … ] } }x-droplet-location: the droplet location
Section titled “x-droplet-location: the droplet location”The droplet location is where the browser reaches the droplets server: the
origin, and the path prefix if there is one, under which the browser loads
/index.js, /env.js, /index.css, /droplets/*, /assets/* and /api/*:
- the host’s own origin when the host proxies those paths
(
https://www.example.com), as every known host does; - the droplets server’s public URL when the page loads
/index.jsfrom it directly (https://drops.example.com).
It differs from Host. Host is the address the request was sent to, so it
says where the host’s server reached the droplets server:
Host: droplets:8000 inside Docker, Host: localhost:8000 on one machine.
Taken from Host alone, the location is one the browser cannot reach. It
also differs from host in a load, which is the page the droplet renders
on (below).
What the location decides: every URL the fragment writes about the server
(its style.css link, the Link header, action URLs, droplet.origin),
the origins the Origin check accepts as
its own, and event.url in handle and +server.ts: the request’s path
and query under the location, prefix included
(https://shop.example/mfe/droplets/hello?who=Ana), while
event.request.url stays the URL the request came in with.
Where it comes from
Section titled “Where it comes from”The server works it out once per request. The first of these that parses and is trusted wins:
x-droplet-location: one URL, its path the prefix (x-droplet-location: https://shop.example/mfe);Forwarded(RFC 7239), its first element’sprotoandhost, the prefix fromX-Forwarded-Prefix;X-Forwarded-ProtoandX-Forwarded-Host, their first values, withX-Forwarded-Portwhen the host has no port of its own, the prefix fromX-Forwarded-Prefix;- the request’s own origin.
A host that fetches fragments on its server sends x-droplet-location. A
reverse proxy needs nothing new: the forwarded headers it already sets are
read once their origin is trusted.
GET /droplets/hello?who=Anax-droplet-location: https://drops.example.com// droplets.config.ts: trust the location the host namesimport { config } from "@dropletsjs/droplets";
export default config({ trustedOrigins: ["https://drops.example.com"] });With location in
droplets.config.ts, none of this runs: every request’s location is
location, no header is read or trusted, and fragments vary on origin
alone. One build serves one location. vite dev ignores location and
works the location out per request; vite preview and wrangler dev serve
the build, so the URLs they write point at the real location.
Any client can send these headers, and the location decides the URLs the server writes about itself. A location from a header (1 to 3) is used only when its origin is:
- the request’s own, or
- in
trustedOrigins(orDROPLETS_TRUSTED_ORIGINS).
One that is not is skipped for the next, with a warning under vite dev,
once per header. Without a list, forwarded headers count only when they name
the request’s own origin. "*" in the list trusts any location; see
Trusting any location before
you use it.
The allow-list is the guard that matters. Fragments answer
Vary: x-droplet-location, forwarded, x-forwarded-host, x-forwarded-proto, x-forwarded-port, x-forwarded-prefix, origin, accept-encoding
when they are cacheable, but CDNs ignore Vary on custom headers (most
only honor Accept-Encoding), so a shared cache can still hand one
request’s fragment to everyone. With a location that is not on the list,
that fragment would point its stylesheet, Link preloads and form actions
at the attacker. The proxy or host should still overwrite these headers
with fixed values (or clear them), never pass on a client’s, and the
droplets server should not be reachable around it.
The first value of a forwarded header is read, never a later one: the
first proxy wrote it, the ones after it only appended. The value must be an
http: or https: URL; credentials, query and hash are dropped, and
anything else (data:, javascript:, a bare word, a host with a path or
@ in it) is skipped. A prefix must start with /, have no //, \,
.., ?, # or control characters, be 256 characters at most, and keep
the origin once joined to it; a prefix that is not is dropped, and the
location is the origin alone. x-droplet-location: https://shop.example/mfe/
puts every URL under https://shop.example/mfe.
The location only shapes the URLs the server writes. The browser takes its
own location from /index.js: the elements load JavaScript, CSS and data
from the URL the page loaded /index.js from, prefix included, whatever the
markup says. Point the <script src> at the same place.
host: where the droplet renders
Section titled “host: where the droplet renders”The location says where the droplet lives; host in load events says
where it renders: the host page. A host tells it, first match wins:
"host"in a POST body:{ "host": "https://shop.example/product/mug", "props": { … } };Origin, as browsers send it;- else the origin of the droplets server’s location.
Origin carries no path, so host.pathname is / unless a body gave one,
or handle read it from Referer or X-Forwarded-Uri; see
host.
Only http: and https: URLs count, without credentials or hash; a source
with anything else is skipped for the next one, never an error. With
trustedOrigins set, a host whose origin is
neither in the list nor the server’s own falls back to the location’s origin.
With host in droplets.config.ts,
host is that origin, with the body’s path and query when the body names a
page on it, else the origin alone; Origin is not read, and trustedOrigins
does not bound it. handle may still set host, from Referer for
instance. vite dev ignores host of the config.
host, the location headers and the props come from the request: any client can send
any value. Use them to render, never to decide who may see what; that is the
job of cookies or a token checked in handle. A response shaped by them is
per request, which is why fragments are not cached by default.
Who sees what
Section titled “Who sees what”What a droplets server learns about the pages that embed it is in Who sees what.
A page on another origin needs cors on the droplets server: see
CORS.
Form actions
Section titled “Form actions”POST /droplets/:id decides by its body’s content type:
| Body | What happens |
|---|---|
application/json |
The fragment renders, as above. With a ?/name key: 400. A form key renders it with that form (for a droplet with actions; ignored otherwise): how an enhanced form swaps in a droplet that does not hydrate. It is client input, as props are. |
application/x-www-form-urlencoded, multipart/form-data |
An action: the query key that starts with / names it (?/add), none is default. |
text/plain |
415. |
The Origin check and the body limits come first. Then the droplet, its
actions export and the name are resolved, and only then is the body read,
by the action itself:
| Case | Status |
|---|---|
The droplet has no actions |
405, allow: GET; the body is never read |
No such action: a name that is not an own function of actions, or not [A-Za-z_][\w-]* (__proto__, constructor…) |
404 |
More than one ?/name |
400 |
actions is not a plain object |
500 |
| Props the schema refuses | 400 |
Props come from the query string, or x-droplet-props; ?/name,
__droplet_return and any __droplet_form_* key are never props, and every other key stays as it
came in request.url. The URL is the same for every caller; the request
decides the answer. One whose accept prefers JSON over HTML gets the
result: application/json (or application/*) named with a weight at
least text/html’s, as an enhanced form sends (accept: application/json)
and any script can. Anything else, a browser’s navigation
(text/html, …, */*;q=0.8) or */* alone, is a native form post, answered
Post/Redirect/Get (below). What the action returns is
answered:
| Result | accept prefers JSON |
Otherwise, with DROPLETS_SECRET |
Otherwise, without it |
|---|---|---|---|
| data, or nothing | 200 { "type": "success", "status": 200, "data": … } |
303 back to the page, the result in its query |
200, the fragment rendered again with form |
fail(status, data) |
status { "type": "failure", "status": …, "data": … } |
303 back to the page, the result in its query |
status, the fragment with form |
redirect(status, location) |
200 { "type": "redirect", "status": …, "location": "…" }, location absolute |
303, location |
303, location |
redirect() to an origin that is not the server’s own, its location’s, a trustedOrigins entry or host’s |
400 { "message": … } |
400, plain text |
400, plain text |
error(status) |
status, { "message": … } |
status, the message |
status, the message |
| data that is not plain JSON | 500 |
500 |
500 |
Action URLs (actionUrl() of $droplets/form, {{action}} in Handlebars)
are <location>/droplets/<id>?/<name>&<props>&__droplet_return=<page>, the
same on the server, in the browser and in a prerender, on the
droplet location, never an
untrusted header’s. <page> is the page the form is on, its origin and
path, encoded: host on the server, window.location in the browser.
In a prerendered render, the location and <page> are tokens filled in per
request, from the request’s location and its host. With
location set, the location is
written in at build. With host set,
the page’s origin is host and its path is filled in per request; its query
never is. With both set, nothing is filled in: <page> is host itself,
so a form posted without JavaScript from such a render goes back to host
(path /), not to the page it was on. Do not prerender a droplet with such
a form, or name the page in its entry.
location is absolute, resolved against host. A fragment rendered with
an action’s result is rendered live, never from the prerendered renders,
with the result in its inline data next to data ({ "data": …, "form": … })
so it hydrates with the same form. What the action (and, for a fragment,
the load that follows) sets with setHeaders and cookies goes out on
every answer but an error, the 303s included.
Post/Redirect/Get
Section titled “Post/Redirect/Get”A native post goes back to the host page, so a reload never posts again:
| Case | Answer |
|---|---|
success or fail() |
303, location: the page (below) without its #hash, its ?/name, __droplet_return and __droplet_form_* keys, plus __droplet_form_<droplet>_<build>=<result> |
redirect() |
303, location: its target |
no page that passes: neither __droplet_return (once, 2 KB at most) nor Referer names one whose origin is this server’s (its location’s included), in trustedOrigins or host’s, outside <location>/droplets/ |
400, plain text; the action does not run |
a redirect() to such an origin, javascript: or anything but http(s) |
400, plain text (400 { "message": … } to a request that prefers JSON: the same check) |
no DROPLETS_SECRET (or under 32 bytes) |
the fragment rendered with form, as the table above; a warning under vite dev, once |
The page, read from the URL and the headers before the body: the
Referer when it has the origin and path __droplet_return names (its
query comes back with it); else __droplet_return (origin and path only);
else the Referer alone. A cross-origin page’s Referer is its origin
alone under the browsers’ default policy, so __droplet_return carries the
path. Origins are compared exactly, http: and https: only, and "*" in
trustedOrigins never counts here: it lets every origin post, never sends
the browser anywhere. The result is
base64url(JSON { status, data?, exp, action }), a ., and
base64url(HMAC-SHA256) over a version tag, the droplet, the build, the
page’s origin and path, and that JSON, keyed with DROPLETS_SECRET. It is valid for five minutes and at most
2 KB; past that, data is dropped (status and action stay), with a warning
under vite dev.
The page loads again. Any render of that droplet whose host carries a
genuine result for it (the fragment, GET or POST, and _data) renders
live with its data as form, 200, cache-control: private, no-store, no-transform;
_data answers { "data": …, "form": … }. The value is checked before it is
read: its length and shape, then the MAC (crypto.subtle.verify), then the
JSON (plain JSON.parse, objects copied without prototypes, __proto__
dropped), the expiry and an action the droplet exports. The MAC is checked
against host’s origin and path: a result minted for one page is ignored
on any other. A value that fails
any of it is ignored. The keys are taken out of host before handle runs
(and again after it, for a host it set): no code of the app sees them.
host must carry the page’s query for this to work: a host fetching
fragments on its server sends its page’s URL as "host" in a POST
render, or as Referer for a handle that reads it with hostFrom; the
browser sends the page’s URL with _data on its own. See
Without JavaScript.
Form posts: the Origin check
Section titled “Form posts: the Origin check”A page on another site can make the browser post a form to your server, with
the user’s cookies and without asking CORS first: a POST, PUT, PATCH
or DELETE whose body is form-urlencoded, multipart or text/plain, or has
no content type at all. Such a request to /droplets/* or /api/* is
answered 403 before handle runs, unless its Origin header is:
- the server’s own origin, or its location’s, or
- in
trustedOriginsindroplets.config.ts, or in theDROPLETS_TRUSTED_ORIGINSenvironment variable (comma-separated, read at runtime, added to the config’s list);"*"trusts every origin; or host’s origin, when it is set.
A form submission without an Origin is refused too: every browser sends
one. So is Origin: null, what a browser sends from a page with
Referrer-Policy: no-referrer: such a page needs
<meta name="referrer" content="strict-origin-when-cross-origin"> for its
forms to post here (see
Post/Redirect/Get).
A request without a content type and without an Origin passes: that
is another server calling, not a browser. This is SvelteKit’s csrf.checkOrigin; csrf: { checkOrigin: false }
turns it off. JSON bodies and GETs are not checked: a JSON post from
another origin needs a CORS preflight, which cors answers. Behind a proxy
that rewrites the request, have it name the public URL in a location
header whose origin is in trustedOrigins, or list the page’s origin in
trustedOrigins.
Body limits
Section titled “Body limits”Bodies over a limit answer 413 before handle runs, judged by
content-length or counted as they stream: 1 MB of JSON, 1 MB of
form-urlencoded or text/plain, 10 MB of multipart or anything else. An
x-droplet-props header over 8 KB answers 431; send larger props in a
POST body. Change them with limits in droplets.config.ts. A body is
JSON by its media type (application/json or a +json suffix, parameters
ignored), the same reading for the limit and for the render: a text/xml
body never renders as a context. What a JSON body or x-droplet-props
carries reaches the droplet as a copy, ordinary objects without an own
__proto__ key, 64 levels deep at most; deeper input counts as no body.
Cookies
Section titled “Cookies”How Set-Cookie gets from a fragment, _data, an action or an endpoint to
the browser, and what a host passes on, is in
Cookies.
Caching
Section titled “Caching”What each route sends as Cache-Control and Vary, and how /index.js
picks up a new build, is in Caching.
Compression
Section titled “Compression”Fragments and _data carry Cache-Control: no-transform, so a proxy in
between leaves their bytes alone (see
HTML rewriters). A
proxy that honors it no longer compresses them either, so the droplets
server does:
- gzip, when asked for. A request whose
Accept-Encodingtakes gzip (gzip;q=0does not) getsContent-Encoding: gzipand noContent-Length. A streamed fragment stays streamed through the compressor. - Not for small or encoded answers. A body under 1024 bytes goes out
plain, judged by its
Content-Lengthor, without one, by reading the first 1024 bytes. So does aHEAD, an answer without a body, and one thathandlegave aContent-Encodingof its own. Vary: Accept-Encodingon every fragment and_dataanswer, compressed or not, merged into theVaryit has.- Redirects, a form action’s JSON,
+server.tsroutes and the files (/assets/*,client.js,style.css,/index.js,/index.css,/env.js) are sent as they are, and a CDN may compress those.
A host that fetches fragments on its server and pastes them into its page
asks for them without Accept-Encoding, or with an HTTP client that
decodes gzip (Node’s fetch, httpx, wp_remote_get, curl with
CURLOPT_ENCODING). One that proxies them to the browser drops
Content-Encoding and Content-Length when its client decoded the body.
nginx’s SSI pastes a subrequest’s body as it comes: clear Accept-Encoding
on the proxied location (see nginx).