Skip to content

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

3

Server HTML: the button works once Svelte hydrates.

Live: rendered by the demo server, hydrated in this page.
src/droplets/counter-svelte/+droplet.svelte
<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}
Terminal window
npx djs add counter --framework svelte

It 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:

PackageInstalled as
@dropletsjs/renderer-sveltea dev dependency, at exactly the version of @dropletsjs/droplets you have
svelte@^5.5.0a dependency

By hand:

Terminal window
npm install svelte
npm install -D @dropletsjs/renderer-svelte

then import { svelte } from "@dropletsjs/renderer-svelte" and svelte() in renderers.

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:

src/droplets/hello/+droplet.svelte
<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?.()}
src/droplets/hello/+error.svelte
<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.

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 under vite dev and vite 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 dev and vite build warn once counter/+error.vue is not a svelte component like the droplet; ignored, the error page is written in the droplet's framework.

  • Compiler options. Runes mode and vitePreprocess() are on, and svelte.config.js is read as usual. svelte({ vitePlugin }) passes options to @sveltejs/vite-plugin-svelte: compilerOptions is spread over { runes: true }, your preprocess runs after vitePreprocess(), your dynamicCompileOptions result is applied after the renderer’s, and any other key replaces the default. With svelte({ plugin: false }) you register the plugin yourself; it then needs runes mode, vitePreprocess(), and css: "injected" for +error.svelte through dynamicCompileOptions.

  • Data with and without experimental.async. The renderer never turns Svelte’s experimental.async on; it reads whether you did, in svelte.config.js or vitePlugin. 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 data is the value there too. When the data rejects, +error.svelte mounts in its place with what handleError returned.
    • with async mode, it gets data as 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.

    DropletProps types data as 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.

  • 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/form sends it with fetch and shows the result in place; without onResult, it calls result.update(). See Actions.

  • Hot updates. Under vite dev, with dev.strategy: "hmr" (the default), an edit to a component goes through @sveltejs/vite-plugin-svelte’s HMR on any page that loads index.js from the dev server. Svelte 5’s HMR swaps the component in place but creates it again, so its $state starts over. An edit to the load brings new data and form to the live component, its state kept; a showing error page is remounted instead. See Hot updates.

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:

Terminal window
pnpm install && pnpm build
pnpm --filter @dropletsjs/example-svelte dev # http://localhost:5173: the devtools page

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