From 75defa67d91052e10cfdb2ad1370b9c26b25b111 Mon Sep 17 00:00:00 2001 From: "svelte-docs-bot[bot]" <196124396+svelte-docs-bot[bot]@users.noreply.github.com> Date: Tue, 25 Nov 2025 02:20:54 +0000 Subject: [PATCH] sync svelte docs --- .../docs/svelte/06-runtime/05-hydratable.md | 66 +++++++++++++++ .../98-reference/.generated/client-errors.md | 27 +++++- .../.generated/client-warnings.md | 19 +++++ .../98-reference/.generated/server-errors.md | 49 +++++++++++ .../.generated/server-warnings.md | 34 ++++++++ .../98-reference/.generated/shared-errors.md | 6 ++ .../docs/svelte/98-reference/20-svelte.md | 13 +++ .../svelte/98-reference/30-runtime-errors.md | 82 ++++++++++++++++++- .../98-reference/30-runtime-warnings.md | 19 +++++ 9 files changed, 311 insertions(+), 4 deletions(-) create mode 100644 apps/svelte.dev/content/docs/svelte/06-runtime/05-hydratable.md create mode 100644 apps/svelte.dev/content/docs/svelte/98-reference/.generated/server-warnings.md diff --git a/apps/svelte.dev/content/docs/svelte/06-runtime/05-hydratable.md b/apps/svelte.dev/content/docs/svelte/06-runtime/05-hydratable.md new file mode 100644 index 0000000000..b840b14dd7 --- /dev/null +++ b/apps/svelte.dev/content/docs/svelte/06-runtime/05-hydratable.md @@ -0,0 +1,66 @@ +--- +NOTE: do not edit this file, it is generated in apps/svelte.dev/scripts/sync-docs/index.ts +title: Hydratable data +--- + +In Svelte, when you want to render asynchronous content data on the server, you can simply `await` it. This is great! However, it comes with a pitfall: when hydrating that content on the client, Svelte has to redo the asynchronous work, which blocks hydration for however long it takes: + +```svelte + + +

{user.name}

+``` + +That's silly, though. If we've already done the hard work of getting the data on the server, we don't want to get it again during hydration on the client. `hydratable` is a low-level API built to solve this problem. You probably won't need this very often -- it will be used behind the scenes by whatever datafetching library you use. For example, it powers [remote functions in SvelteKit](/docs/kit/remote-functions). + +To fix the example above: + +```svelte + + +

{user.name}

+``` + +This API can also be used to provide access to random or time-based values that are stable between server rendering and hydration. For example, to get a random number that doesn't update on hydration: + +```ts +import { hydratable } from 'svelte'; +const rand = hydratable('random', () => Math.random()); +``` + +If you're a library author, be sure to prefix the keys of your `hydratable` values with the name of your library so that your keys don't conflict with other libraries. + +## Serialization + +All data returned from a `hydratable` function must be serializable. But this doesn't mean you're limited to JSON — Svelte uses [`devalue`](https://npmjs.com/package/devalue), which can serialize all sorts of things including `Map`, `Set`, `URL`, and `BigInt`. Check the documentation page for a full list. In addition to these, thanks to some Svelte magic, you can also fearlessly use promises: + +```svelte + + +{await promises.one} +{await promises.two} +``` diff --git a/apps/svelte.dev/content/docs/svelte/98-reference/.generated/client-errors.md b/apps/svelte.dev/content/docs/svelte/98-reference/.generated/client-errors.md index fa8533928a..8601a728a7 100644 --- a/apps/svelte.dev/content/docs/svelte/98-reference/.generated/client-errors.md +++ b/apps/svelte.dev/content/docs/svelte/98-reference/.generated/client-errors.md @@ -130,12 +130,16 @@ $effect(() => { Often when encountering this issue, the value in question shouldn't be state (for example, if you are pushing to a `logs` array in an effect, make `logs` a normal array rather than `$state([])`). In the rare cases where you really _do_ need to write to state in an effect — [which you should avoid]($effect#When-not-to-use-$effect) — you can read the state with [untrack](svelte#untrack) to avoid adding it as a dependency. -### experimental_async_fork +### flush_sync_in_effect ``` -Cannot use `fork(...)` unless the `experimental.async` compiler option is `true` +Cannot use `flushSync` inside an effect ``` +The `flushSync()` function can be used to flush any pending effects synchronously. It cannot be used if effects are currently being flushed — in other words, you can call it after a state change but _not_ inside an effect. + +This restriction only applies when using the `experimental.async` option, which will be active by default in Svelte 6. + ### fork_discarded ``` @@ -154,6 +158,25 @@ Cannot create a fork inside an effect or when state changes are pending `getAbortSignal()` can only be called inside an effect or derived ``` +### hydratable_missing_but_required + +``` +Expected to find a hydratable with key `%key%` during hydration, but did not. +``` + +This can happen if you render a hydratable on the client that was not rendered on the server, and means that it was forced to fall back to running its function blockingly during hydration. This is bad for performance, as it blocks hydration until the asynchronous work completes. + +```svelte + +``` + ### hydration_failed ``` diff --git a/apps/svelte.dev/content/docs/svelte/98-reference/.generated/client-warnings.md b/apps/svelte.dev/content/docs/svelte/98-reference/.generated/client-warnings.md index c95ace2229..4deb338521 100644 --- a/apps/svelte.dev/content/docs/svelte/98-reference/.generated/client-warnings.md +++ b/apps/svelte.dev/content/docs/svelte/98-reference/.generated/client-warnings.md @@ -140,6 +140,25 @@ The easiest way to log a value as it changes over time is to use the [`$inspect` %handler% should be a function. Did you mean to %suggestion%? ``` +### hydratable_missing_but_expected + +``` +Expected to find a hydratable with key `%key%` during hydration, but did not. +``` + +This can happen if you render a hydratable on the client that was not rendered on the server, and means that it was forced to fall back to running its function blockingly during hydration. This is bad for performance, as it blocks hydration until the asynchronous work completes. + +```svelte + +``` + ### hydration_attribute_changed ``` diff --git a/apps/svelte.dev/content/docs/svelte/98-reference/.generated/server-errors.md b/apps/svelte.dev/content/docs/svelte/98-reference/.generated/server-errors.md index 6263032212..4d05e04207 100644 --- a/apps/svelte.dev/content/docs/svelte/98-reference/.generated/server-errors.md +++ b/apps/svelte.dev/content/docs/svelte/98-reference/.generated/server-errors.md @@ -1,5 +1,13 @@ +### async_local_storage_unavailable + +``` +The node API `AsyncLocalStorage` is not available, but is required to use async server rendering. +``` + +Some platforms require configuration flags to enable this API. Consult your platform's documentation. + ### await_invalid ``` @@ -14,6 +22,39 @@ You (or the framework you're using) called [`render(...)`](svelte-server#render) The `html` property of server render results has been deprecated. Use `body` instead. ``` +### hydratable_clobbering + +``` +Attempted to set `hydratable` with key `%key%` twice with different values. + +%stack% +``` + +This error occurs when using `hydratable` multiple times with the same key. To avoid this, you can: +- Ensure all invocations with the same key result in the same value +- Update the keys to make both instances unique + +```svelte + +``` + +### hydratable_serialization_failed + +``` +Failed to serialize `hydratable` data for key `%key%`. + +`hydratable` can serialize anything [`uneval` from `devalue`](https://npmjs.com/package/uneval) can, plus Promises. + +Cause: +%stack% +``` + ### lifecycle_function_unavailable ``` @@ -21,3 +62,11 @@ The `html` property of server render results has been deprecated. Use `body` ins ``` Certain methods such as `mount` cannot be invoked while running in a server context. Avoid calling them eagerly, i.e. not during render. + +### server_context_required + +``` +Could not resolve `render` context. +``` + +Certain functions such as `hydratable` cannot be invoked outside of a `render(...)` call, such as at the top level of a module. diff --git a/apps/svelte.dev/content/docs/svelte/98-reference/.generated/server-warnings.md b/apps/svelte.dev/content/docs/svelte/98-reference/.generated/server-warnings.md new file mode 100644 index 0000000000..c4a7fbefef --- /dev/null +++ b/apps/svelte.dev/content/docs/svelte/98-reference/.generated/server-warnings.md @@ -0,0 +1,34 @@ + + +### unresolved_hydratable + +``` +A `hydratable` value with key `%key%` was created, but at least part of it was not used during the render. + +The `hydratable` was initialized in: +%stack% +``` + +The most likely cause of this is creating a `hydratable` in the `script` block of your component and then `await`ing +the result inside a `svelte:boundary` with a `pending` snippet: + +```svelte + + + +

{(await user).name}

+ + {#snippet pending()} +
Loading...
+ {/snippet} + +``` + +Consider inlining the `hydratable` call inside the boundary so that it's not called on the server. + +Note that this can also happen when a `hydratable` contains multiple promises and some but not all of them have been used. diff --git a/apps/svelte.dev/content/docs/svelte/98-reference/.generated/shared-errors.md b/apps/svelte.dev/content/docs/svelte/98-reference/.generated/shared-errors.md index 07e13dea45..136b3f4957 100644 --- a/apps/svelte.dev/content/docs/svelte/98-reference/.generated/shared-errors.md +++ b/apps/svelte.dev/content/docs/svelte/98-reference/.generated/shared-errors.md @@ -1,5 +1,11 @@ +### experimental_async_required + +``` +Cannot use `%name%(...)` unless the `experimental.async` compiler option is `true` +``` + ### invalid_default_snippet ``` diff --git a/apps/svelte.dev/content/docs/svelte/98-reference/20-svelte.md b/apps/svelte.dev/content/docs/svelte/98-reference/20-svelte.md index f435677a67..410a514c76 100644 --- a/apps/svelte.dev/content/docs/svelte/98-reference/20-svelte.md +++ b/apps/svelte.dev/content/docs/svelte/98-reference/20-svelte.md @@ -21,6 +21,7 @@ import { getAllContexts, getContext, hasContext, + hydratable, hydrate, mount, onDestroy, @@ -433,6 +434,18 @@ function hasContext(key: any): boolean; +## hydratable + +
+ +```dts +function hydratable(key: string, fn: () => T): T; +``` + +
+ + + ## hydrate Hydrates a component on the given target and returns the exports and potentially the props (if compiled with `accessors: true`) of the component diff --git a/apps/svelte.dev/content/docs/svelte/98-reference/30-runtime-errors.md b/apps/svelte.dev/content/docs/svelte/98-reference/30-runtime-errors.md index a0b0e874dc..ab60a1baef 100644 --- a/apps/svelte.dev/content/docs/svelte/98-reference/30-runtime-errors.md +++ b/apps/svelte.dev/content/docs/svelte/98-reference/30-runtime-errors.md @@ -137,12 +137,16 @@ $effect(() => { Often when encountering this issue, the value in question shouldn't be state (for example, if you are pushing to a `logs` array in an effect, make `logs` a normal array rather than `$state([])`). In the rare cases where you really _do_ need to write to state in an effect — [which you should avoid]($effect#When-not-to-use-$effect) — you can read the state with [untrack](svelte#untrack) to avoid adding it as a dependency. -### experimental_async_fork +### flush_sync_in_effect ``` -Cannot use `fork(...)` unless the `experimental.async` compiler option is `true` +Cannot use `flushSync` inside an effect ``` +The `flushSync()` function can be used to flush any pending effects synchronously. It cannot be used if effects are currently being flushed — in other words, you can call it after a state change but _not_ inside an effect. + +This restriction only applies when using the `experimental.async` option, which will be active by default in Svelte 6. + ### fork_discarded ``` @@ -161,6 +165,25 @@ Cannot create a fork inside an effect or when state changes are pending `getAbortSignal()` can only be called inside an effect or derived ``` +### hydratable_missing_but_required + +``` +Expected to find a hydratable with key `%key%` during hydration, but did not. +``` + +This can happen if you render a hydratable on the client that was not rendered on the server, and means that it was forced to fall back to running its function blockingly during hydration. This is bad for performance, as it blocks hydration until the asynchronous work completes. + +```svelte + +``` + ### hydration_failed ``` @@ -279,6 +302,14 @@ If it's possible to resolve the error inside the `onerror` callback, you must at +### async_local_storage_unavailable + +``` +The node API `AsyncLocalStorage` is not available, but is required to use async server rendering. +``` + +Some platforms require configuration flags to enable this API. Consult your platform's documentation. + ### await_invalid ``` @@ -293,6 +324,39 @@ You (or the framework you're using) called [`render(...)`](svelte-server#render) The `html` property of server render results has been deprecated. Use `body` instead. ``` +### hydratable_clobbering + +``` +Attempted to set `hydratable` with key `%key%` twice with different values. + +%stack% +``` + +This error occurs when using `hydratable` multiple times with the same key. To avoid this, you can: +- Ensure all invocations with the same key result in the same value +- Update the keys to make both instances unique + +```svelte + +``` + +### hydratable_serialization_failed + +``` +Failed to serialize `hydratable` data for key `%key%`. + +`hydratable` can serialize anything [`uneval` from `devalue`](https://npmjs.com/package/uneval) can, plus Promises. + +Cause: +%stack% +``` + ### lifecycle_function_unavailable ``` @@ -301,11 +365,25 @@ The `html` property of server render results has been deprecated. Use `body` ins Certain methods such as `mount` cannot be invoked while running in a server context. Avoid calling them eagerly, i.e. not during render. +### server_context_required + +``` +Could not resolve `render` context. +``` + +Certain functions such as `hydratable` cannot be invoked outside of a `render(...)` call, such as at the top level of a module. + ## Shared errors +### experimental_async_required + +``` +Cannot use `%name%(...)` unless the `experimental.async` compiler option is `true` +``` + ### invalid_default_snippet ``` diff --git a/apps/svelte.dev/content/docs/svelte/98-reference/30-runtime-warnings.md b/apps/svelte.dev/content/docs/svelte/98-reference/30-runtime-warnings.md index 7d5bd44cec..51505ed616 100644 --- a/apps/svelte.dev/content/docs/svelte/98-reference/30-runtime-warnings.md +++ b/apps/svelte.dev/content/docs/svelte/98-reference/30-runtime-warnings.md @@ -147,6 +147,25 @@ The easiest way to log a value as it changes over time is to use the [`$inspect` %handler% should be a function. Did you mean to %suggestion%? ``` +### hydratable_missing_but_expected + +``` +Expected to find a hydratable with key `%key%` during hydration, but did not. +``` + +This can happen if you render a hydratable on the client that was not rendered on the server, and means that it was forced to fall back to running its function blockingly during hydration. This is bad for performance, as it blocks hydration until the asynchronous work completes. + +```svelte + +``` + ### hydration_attribute_changed ```