Skip to content

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.

src/droplets/docs/+droplet.server.ts
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;
  • 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 of dist/client named anew every build that only the Worker knows. Nothing is bundled.
  • Listed props are served from the store (and _data answers from it). Other props render live, or answer 404 when ssr = 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 answers error() or redirect() warns at build and renders live.
  • Renders go through handle, with building from $droplets/env set to true.
  • vite dev renders everything live, and ignores the configured host: an entry without its own host is host-agnostic there.

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.

src/droplets/banner/+droplet.server.ts
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:

  1. the entry’s host;
  2. host in droplets.config.ts (host: "https://shop.example");
  3. none: the render is host-agnostic.
  • For the entry’s host, the loads get a real URL, and the render is stored under its props and that page’s origin and path. A request gets it only when its own host matches.
  • For the configured host, the loads get a real URL of that origin: host.hostname, host.protocol and host.port read as they are, and host.search and host.hash are empty. Its page is not known at build, so host.pathname and host.href are 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 location set too, a render for the configured host holds nothing to fill in: host.pathname is /, host.href is 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.

Serving a prerendered dropletAfter handle, a request for a prerendered droplet looks for a stored render: first the one made for its page, origin and path; then the one made for host of the config, by origin; then the host-agnostic one for the same props. A stored render has its tokens filled in with this request's host, page path and location; with location and host both fixed it holds none. With no stored render it renders live, or answers 404 when ssr is false. Either way transform runs per request, and the fragment goes out.A request for these propsafter handlestored for this page?nostored for host of theconfig?nostored without a host?the stored renderHTML and data, as builtyestokens filled inhost, page path and location: thisrequest's; none when both are fixednorenders live404 when ssr = falsetransformper request, stored or livethe fragmentServing a prerendered dropletAfter handle, a request for a prerendered droplet looks for a stored render: first the one made for its page, origin and path; then the one made for host of the config, by origin; then the host-agnostic one for the same props. A stored render has its tokens filled in with this request's host, page path and location; with location and host both fixed it holds none. With no stored render it renders live, or answers 404 when ssr is false. Either way transform runs per request, and the fragment goes out.A request for thesepropsafter handlestored for thispage?nostored for host ofthe config?nostored without ahost?the storedrenderHTML and data, asbuiltyestokens filled inhost, page pathand location: thisrequest's; nonewhen both arefixednorenders live404 when ssr = falsetransformper request, storedor livethe fragment
The most specific stored render wins; its tokens are filled in per request, and transform runs on stored and live renders alike.

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.

  • Tokens. In a host-agnostic render, host.origin, host.pathname and host.href (and String(host), JSON.stringify) give the tokens __$DROPLET_HOST$__ and __$DROPLET_PATH$__. Without location in the config, every render made at build also holds the droplet location as http://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 sale above is stored as __$DROPLET_HOST$__/sale, in its markup and its inline data. Every request that serves it gets the tokens replaced with its own host and location, after handle and before transform: in the HTML (escaped for attributes), in the inline data, and in their encodeURIComponent forms.
  • 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 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.