Prerendering
export const prerender = true renders the droplet at build time, once for
each event entries in +droplet.server.ts returns ([{}] without it). An
event is what the loads run with: props, and optionally host.
import type { Entries } from "$droplets/server";
export const entries = (() => [ { props: { page: 1 } }, { props: { page: 2 } }, { props: { page: 3 }, host: "https://shop.example/docs" },]) satisfies Entries;Where the renders live
Section titled “Where the renders live”- With the server, never as public files. Renders are read per
request: from
dist/server/_prerendered/on Node, Bun and Deno; on Workers through the assets binding, from a directory ofdist/clientnamed anew every build that only the Worker knows. Nothing is bundled. - Listed props are served from the store (and
_dataanswers from it). Other props render live, or answer404whenssr = false. A render made for a host page serves that page only (origin and path, never the query); see below. - A failed load is stored too: a prop set whose load fails is stored as
its error page, served with a
500. One that answerserror()orredirect()warns at build and renders live. - Renders go through
handle, withbuildingfrom$droplets/envset totrue. vite devrenders everything live, and ignores the configuredhost: an entry without its ownhostis host-agnostic there.
host at build
Section titled “host at build”A render made at build has no request, so it may not know the page it will
be shown on. The rule: in a host-agnostic render, read only
host.origin, host.pathname and host.href (or String(host)). They
are filled in with each request’s page; anything else stops the build.
import type { LoadEvent } from "./$types";
export const load = ({ host }: LoadEvent) => ({ sale: `${host.origin}/sale`, // fine: filled in per request // host.searchParams.get("ref") would stop the build});Each entry renders for the first host page it can have:
- the entry’s
host; hostindroplets.config.ts(host: "https://shop.example");- none: the render is host-agnostic.
- For the entry’s
host, the loads get a realURL, and the render is stored under its props and that page’s origin and path. A request gets it only when its ownhostmatches. - For the configured
host, the loads get a realURLof that origin:host.hostname,host.protocolandhost.portread as they are, andhost.searchandhost.hashare empty. Its page is not known at build, sohost.pathnameandhost.hrefare filled in with each request’s page. It is stored under its props and the origin alone, and serves every page of that origin. - With
locationset too, a render for the configuredhostholds nothing to fill in:host.pathnameis/,host.hrefis the origin’s root, and the render is served exactly as stored.
A request looks for the render made for its page, then the one for the
configured host, then the host-agnostic one of the same props; with none,
it renders live.
When a render reads another field of a host-agnostic host
(host.searchParams, host.hostname, …), the build stops, even when the
droplet’s code catches the error: the render answers 500 with
x-droplets-prerender-error: host, and vite build fails with
HostUrlPropsErrorInPrerender’s message. Give that entry a host, set
host in droplets.config.ts, or render it live.
cookies stop the build the same way: there is
no request at build.
How the values are filled in
Section titled “How the values are filled in”- Tokens. In a host-agnostic render,
host.origin,host.pathnameandhost.href(andString(host),JSON.stringify) give the tokens__$DROPLET_HOST$__and__$DROPLET_PATH$__. Withoutlocationin the config, every render made at build also holds the droplet location ashttp://droplets.invalid/__$DROPLET_LOCATION$__(droplet.origin, action URLs, imported files). Each token carries the build’s nonce (__$DROPLET_HOST_<nonce>$__), so content cannot fake one. - Per request. The banner’s
saleabove is stored as__$DROPLET_HOST$__/sale, in its markup and its inline data. Every request that serves it gets the tokens replaced with its ownhostand location, afterhandleand beforetransform: in the HTML (escaped for attributes), in the inline data, and in theirencodeURIComponentforms. - Text and attributes only. The values are HTML-escaped. Inside an
inline
<script>or<style>they get HTML escaping, not JavaScript or CSS escaping, so do not use them there.
transform
Section titled “transform”transform in +droplet.server.ts rewrites the droplet’s HTML on every
request, prerendered or live, with the request’s event. What a build-time
render cannot know goes here:
import type { TransformEvent } from "$droplets/server";
const escapeHtml = (text: string) => text.replace(/[&<>"']/g, (c) => `&#${c.charCodeAt(0)};`);
export const transform = ({ html, host }: TransformEvent) => html.replaceAll("@HOST@", () => escapeHtml(host.host));transform writes into HTML, and host comes from the request: escape what
you splice in, and pass the replacement as a function, so $& or $' in
it is not read as a pattern. A list of functions runs in order.
error() and redirect() stop it as they stop a load: the fragment answers
with that status, or the redirect. transform runs on fragments only;
_data answers what the load returned. The
shop demo
redirects an old link from its transform.