Hydratable
Reuse a component effect's server-rendered result while the page hydrates.Since 5.0.0, awaited component effects run during server rendering, and the
browser runs them again while it hydrates the page. That is how a native await in a Svelte component behaves, and it is the safe default: an effect
that reads the browser always sees the browser.
Some effects return the same value wherever they run. Running a forecast lookup twice, once to render the HTML and once more to hydrate it, wastes a request and can briefly show a loading state the server already filled in.
Hydratable(key, effect) is the effect counterpart of Svelte's hydratable(key, fn). The server runs the effect and embeds its result in
the page under key. The hydrating client finds that result and uses it
instead of running the effect again.
<script lang="ts" effect>
import { Hydratable } from "svelte-effect-runtime";
import { Weather } from "$lib/weather";
let { city }: { city: string } = $props();
const forecast = $derived(yield* Hydratable(`forecast:${city}`, Weather.forecast(city)));
</script>
<h2>{forecast.summary}</h2>
<p>{yield* Hydratable(`alerts:${city}`, Weather.alerts(city))}</p>After hydration the effect behaves normally. When city changes, both
expressions run again in the browser.
Where it applies
Hydratable takes effect when it is the first effect a component expression
yields:
{yield* Hydratable("profile", LoadProfile())}<script lang="ts" effect>
const profile = $derived(yield* Hydratable("profile", LoadProfile()));
</script>Anywhere else, such as inside a larger Effect.gen or after another yield* in the same expression, it simply runs the wrapped effect.
Choose the key
The key identifies the result in the page, so it must be unique per value. Include every input the effect depends on:
Hydratable(`forecast:${city}`, Weather.forecast(city));
Hydratable(`invoice:${account_id}:${invoice_id}`, Billing.invoice(account_id, invoice_id));Two expressions that share a key would receive the same server result.
When the client runs it anyway
The server embeds results with devalue. A value it cannot serialize, such
as an object holding functions or a class instance, is not embedded, and the
client runs the effect again. An effect that fails on the server is not embedded
either, so the client gets its own attempt.
When not to use it
Only wrap effects whose result is the same on the server and in the browser. Anything that reads the environment must keep running on the client:
<!-- Wrong: the server's answer would replace the browser's. -->
<p>{yield* Hydratable("theme", ReadSavedTheme())}</p>
<p>{yield* Hydratable("now", Effect.sync(() => Date.now()))}</p>
<!-- Right: these run again while hydrating. -->
<p>{yield* ReadSavedTheme()}</p>
<p>{yield* Effect.sync(() => Date.now())}</p>Local storage, window, the viewport, the current time, and random values
all differ between the two renders.
Remote Query results do not need Hydratable. SvelteKit
already serializes them into the page and reuses them while hydrating.