Svelte
Svelte 5 components (5.5 or later), compiled in runes mode, rendered on the server and hydrated in place. The droplet below is a Svelte component served by the demo server: its load sets the start, Svelte renders it to HTML, and the button works once the bundle hydrates it.
counter · Svelte
Server HTML: the button works once Svelte hydrates.
<script module lang="ts"> export const ssr = true; export const hydrate = true;</script>
<script lang="ts"> import type { DropletProps } from "./$types";
// What the server load returned. A value here: without Svelte's // experimental.async the renderer waits for it before mounting. let { data }: DropletProps = $props();
let added = $state(0); // False in the server's HTML; true once this component runs in the browser. let hydrated = $state(false); $effect(() => { hydrated = true; });</script>
{#await data then { framework, start }} <section class="demo-card" data-hydrated={hydrated}> <p class="demo-row"><span class="demo-tag">counter · {framework}</span></p> <p class="demo-row"> <output class="demo-title" aria-live="polite">{start + added}</output> <button type="button" class="demo-button" onclick={() => (added += 1)}>Add one</button> </p> <p class="demo-muted"> {hydrated ? `Hydrated: ${framework} runs the button in this tab.` : `Server HTML: the button works once ${framework} hydrates.`} </p> </section>{/await}import type { LoadEvent } from "./$types";
/** * Runs on the server only. The count starts where the server says, and the * name of the framework comes with it. The same for everyone, so a browser * (or a cache in front) may keep it for five minutes. */export const load = ({ setHeaders }: LoadEvent) => { setHeaders({ "cache-control": "public, max-age=300" }); return { framework: "Svelte", start: 3 };};Add it to a project
Section titled “Add it to a project”npx djs add counter --framework svelteIt installs what the project lacks and adds svelte() to renderers invite.config.ts, asking first, then writes src/droplets/counter/+droplet.svelte.
Every step it takes is in Add a renderer. What it installs for Svelte:
| Package | Installed as |
|---|---|
@dropletsjs/renderer-svelte | a dev dependency, at exactly the version of @dropletsjs/droplets you have |
svelte@^5.5.0 | a dependency |
By hand:
npm install sveltenpm install -D @dropletsjs/renderer-sveltethen import { svelte } from "@dropletsjs/renderer-svelte" and svelte() in renderers.
The files
Section titled “The files”| File | What it is |
|---|---|
+droplet.svelte |
The component. Its flags go in <script module> (or <script context="module">). |
+error.svelte |
The error page, optional. It follows the droplet’s flags, and its styles travel with its markup. |
*.svelte.ts, *.svelte.js |
Svelte modules with runes, anywhere in src/. They are Svelte’s own: only Svelte droplets may import them. |
+droplet.ts, +droplet.server.ts |
The loads, as for every framework: Writing droplets. |
.svelte is Svelte’s alone, so nothing decides between renderers here: any
+droplet.svelte is a Svelte droplet.
The flags are read from the <script module> block alone, as literal
export const declarations. A flag in the instance <script>, the markup,
a comment, +droplet.ts or +droplet.server.ts is ignored.
The props are data (what the loads returned), form after a form action,
and children, a snippet that renders the host’s content:
<script module lang="ts"> export const hydrate = true;</script>
<script lang="ts"> import type { DropletProps } from "./$types";
let { data, children }: DropletProps = $props(); let clicks = $state(0);</script>
{#await data then { greeting }} <h1>{greeting}</h1>{/await}<button onclick={() => (clicks += 1)}>{clicks}</button>{@render children?.()}<script lang="ts"> import type { DropletErrorProps } from "./$types"; let { error, children }: DropletErrorProps = $props();</script>
<p class="oops">{error.message}</p>{@render children?.()}
<style> .oops { color: crimson; }</style>error is what handleError in +droplet.server.ts (or +droplet.ts)
returned; see Errors.
What it supports
Section titled “What it supports”| Server rendering | yes: ssr = true, the default; ssr = false mounts it in the browser only |
hydrate |
true (the default), "visible", "interactive", false |
| Prerendering | yes: prerender = true, once per event entries returns: Prerendering |
| Forms | use:enhanceDropletForm of @dropletsjs/renderer-svelte/form |
Two mistakes fail vite build, and vite dev as well, with a message that
names the fix:
-
a Svelte droplet that reaches another configured framework, even through a neutral file:
droplets: a svelte droplet imports vue code: src/droplets/counter/+droplet.svelte -> src/lib/format.ts -> vue/dist/vue.runtime.esm-bundler.js. A droplet uses its own framework's modules and neutral code only. -
a second component in the folder:
droplets: counter/ has 2 droplet components (+droplet.svelte, +droplet.vue); keep one
Other mistakes are ignored, with a warning:
-
a flag that is not a literal, such as
export const hydrate = isMobile, warns undervite devandvite build, and the flag keeps its default:[droplets:framework] `export const hydrate` must be true, false, "visible" or "interactive"; ignoring it { droplet: 'counter', found: 'isMobile' } -
an
+error.vue(or any error page in another framework) next to a Svelte droplet is not used;vite devandvite buildwarn oncecounter/+error.vue is not a svelte component like the droplet; ignored, the error page is written in the droplet's framework.
Specifics
Section titled “Specifics”-
Compiler options. Runes mode and
vitePreprocess()are on, andsvelte.config.jsis read as usual.svelte({ vitePlugin })passes options to@sveltejs/vite-plugin-svelte:compilerOptionsis spread over{ runes: true }, yourpreprocessruns aftervitePreprocess(), yourdynamicCompileOptionsresult is applied after the renderer’s, and any other key replaces the default. Withsvelte({ plugin: false })you register the plugin yourself; it then needs runes mode,vitePreprocess(), andcss: "injected"for+error.sveltethroughdynamicCompileOptions. -
Data with and without
experimental.async. The renderer never turns Svelte’sexperimental.asyncon; it reads whether you did, insvelte.config.jsorvitePlugin. A hydrated droplet always gets the value. A droplet mounted from scratch (client-only, remounted in dev):- without async mode, the renderer waits for its data before it mounts, so
datais the value there too. When the data rejects,+error.sveltemounts in its place with whathandleErrorreturned. - with async mode, it gets
dataas a promise: read it with{(await data).greeting}. With an error page, the droplet renders under the renderer’s<svelte:boundary>, and a rejection (or any render error) shows+error.svelte.
DropletPropstypesdataas the value:{data.greeting}type-checks, and so do{(await data).greeting}and{#await data then …}(as in the demo), which read it in both modes. Without{:catch},{#await}does not report a rejection itself. - without async mode, the renderer waits for its data before it mounts, so
-
Children.
{@render children?.()}renders the host’s content. It may sit under an{#if}: the content is moved out and back, never destroyed. -
The error page compiles with injected CSS, so its
<style>travels with the markup wherever it renders: on the server in the fragment’s head, in the browser when it mounts, even where the droplet’s stylesheet never loaded. -
Forms.
actionUrl("add")of$droplets/form, called in<script>, gives the URL the form posts to, then<form method="post" action={add}>.use:enhanceDropletForm={{ action: "add" }}of@dropletsjs/renderer-svelte/formsends it withfetchand shows the result in place; withoutonResult, it callsresult.update(). See Actions. -
Hot updates. Under
vite dev, withdev.strategy: "hmr"(the default), an edit to a component goes through@sveltejs/vite-plugin-svelte’s HMR on any page that loadsindex.jsfrom the dev server. Svelte 5’s HMR swaps the component in place but creates it again, so its$statestarts over. An edit to the load brings newdataandformto the live component, its state kept; a showing error page is remounted instead. See Hot updates.
The example
Section titled “The example”examples/frameworks/svelte
has one droplet per mode, client (ssr = false), ssr-hydrate (with
+error.svelte) and ssr-nohydrate (hydrate = false), with loads, a props
schema, /api endpoints, env variables and a handle hook. It also has a
script droplet, page-views, which gets a count from
its server load and posts each view to src/api/page-views. Its droplets
render in <djs-svelte>. From a clone of the repository:
pnpm install && pnpm buildpnpm --filter @dropletsjs/example-svelte dev # http://localhost:5173: the devtools pagepnpm --filter @dropletsjs/example-svelte build then start serves it on
http://localhost:8000; /droplets/ssr-hydrate?who=Ana is the fragment a
host pastes into its page.