feat: `hydratable` and a more consistent remote functions model by elliott-with-the-longest-name-on-github · Pull Request #15533 · sveltejs/kit

elliott-with-the-longest-name-on-github · 2026-03-11T01:06:42Z

This PR makes a number of substantial changes to how remote queries work.

`hydratable`

Implementation-wise, it replaces our custom transport solution with hydratable for queries that are used during render -- this method of transport is more correct and prevents us from accidentally using stale data for queries in a small subset of cases. There's one breaking side effect of this: If you didn't render a query on the server, you can't render it during hydration.

It means this:

 <script>
  import { browser } from '$app/environment';
  const count = browser ? get_count() : null;
</script>

would throw during hydration because get_count tried to access cached data that did not exist. This is almost always an undesirable mistake: It means you introduced a waterfall on the client and blocked hydration. If you really do want this, you'd do something like this instead:

<script>
  import { onMount } from 'svelte';
  let count;
  onMount(() => {
    count = get_count();
  });
</script>

New rules around query usage

From now on, on the client, you can only access a query's data if that query is:

created in a tracking context (i.e. at the top level of a script block, in a derived, in an effect, etc -- basically somewhere Svelte's reactivity system can "see" the query)
the tracking context in which the query is created is still alive

It may be easier to illustrate when you can't create and use a query on the client:

universal load
event handlers
the top level of modules

We're making this change because otherwise it's basically impossible to reliably cache queries across your app. However, for most use cases, this probably doesn't cause any pain:

you can still use the methods that don't access query data anywhere: .refresh, .set, .withOverride are all available
if you need to get a query's data in a non-reactive context, you can make a one-off request to get that query's data with query().run(), which will return a plain old Promise resolving to your data

Bugfixes

queries are now wrapped in their own $effect.root when created. This prevents them from associating with their parent effect, making their usage more predictable when retrieved from the cache
.refresh is now a noop if there is no cached instance of the query, meaning you won't have a useless query request in some circumstances
caching / deduplicating should be more reliable, and it should be more obvious when you're trying to do something insane
there should now be no cases where stale cached data is used post-hydration (thank you, hydratable!)

changeset-bot · 2026-03-11T01:06:46Z

⚠️ No Changeset found

Latest commit: 72bc665

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

svelte-docs-bot · 2026-03-11T01:08:16Z

Preview: https://svelte-dev-git-preview-kit-15533-svelte.vercel.app/

packages/kit/src/runtime/client/remote-functions/prerender.svelte.js

packages/kit/src/runtime/client/remote-functions/query.svelte.js

…rowser consoles This commit fixes the issue reported at packages/kit/src/runtime/client/remote-functions/query.svelte.js:58 **Bug Explanation:** Three debug console.log statements were left in the production code at: * Line 58: `console.log(cache_key + ' bypassed hydratable');` * Line 292: `console.log(this._key, 'serving from the cache');` * Line 295: `console.log(this._key, 'made it past the cache');` These statements appear to be development debugging aids that were not removed before committing. The codebase has a clear pattern for console.log usage: 1. In build/CLI tools (acceptable since those run in Node.js during development) 2. Guarded by `DEV` checks for runtime code (e.g., line 671 in respond.js uses `if (DEV && ...) { console.log(...) }`) The unguarded console.log statements in query.svelte.js would execute on every query run/cache check in production, spamming end users' browser consoles with internal debugging messages like "query-key serving from the cache" and "query-key bypassed hydratable". **Fix:** Removed all three debug console.log statements since they serve no purpose for production users and were clearly left in accidentally (evidenced by commit messages like "i think it work" indicating development-in-progress code). Co-authored-by: Vercel <vercel[bot]@users.noreply.github.com> Co-authored-by: elliott-with-the-longest-name-on-github <hello@ell.iott.dev>

packages/adapter-netlify/test/apps/split/src/routes/remote/query/+page.svelte

Rich-Harris · 2026-03-13T20:15:27Z

packages/kit/src/exports/public.d.ts

+	 * Unlike awaiting the resource directly, this can be used anywhere
+	 * (load functions, event handlers, etc) without requiring a reactive context.


we'd talked about making it not work in effects — is that the plan? (or already implemented, though i'll figure that out by carrying on reading) if so this comment will need to change

not implemented. though I'm still ambivalent. I don't think it would be too hard to implement and it might be a good idea.

Rich-Harris · 2026-03-13T20:47:56Z

packages/kit/src/runtime/app/server/remote/query.js

+			start: () => get_response(__, arg, state, get_remote_function_result),
+			refresh: () => get_remote_function_result()


we can simplify this signature

Suggested change

start: () => get_response(__, arg, state, get_remote_function_result),

refresh: () => get_remote_function_result()

get_remote_function_result

Rich-Harris · 2026-03-13T21:03:54Z

packages/kit/src/runtime/client/remote-functions/shared.svelte.js

-		'x-sveltekit-search': page.url.search
-	}));
+	return untrack(() => {
+		const url = navigating.current?.to?.url ?? page.url;


this feels a little brittle — you could navigate, triggering a load function that will eventually call a query, then navigate again before it actually happens. not yet sure what the right way to think about it is

feat: hydratable and a more consistent remote functions model

68c96a1

another batch reviewed

7079723

Rich-Harris reviewed Mar 11, 2026

View reviewed changes

packages/kit/src/runtime/client/remote-functions/prerender.svelte.js Outdated Show resolved Hide resolved

Rich-Harris mentioned this pull request Mar 12, 2026

fix: freeze deriveds once their containing effects are destroyed sveltejs/svelte#17921

Draft

6 tasks

i think it work

3b0ed66

elliott-with-the-longest-name-on-github marked this pull request as ready for review March 13, 2026 19:25

elliott-with-the-longest-name-on-github added 2 commits March 13, 2026 13:25

types

6370070

fix test

0a8ba50

vercel bot reviewed Mar 13, 2026

View reviewed changes

packages/kit/src/runtime/client/remote-functions/query.svelte.js Outdated Show resolved Hide resolved

Rich-Harris reviewed Mar 13, 2026

View reviewed changes

packages/adapter-netlify/test/apps/split/src/routes/remote/query/+page.svelte Show resolved Hide resolved

whoops

e2ab37f

Rich-Harris reviewed Mar 13, 2026

View reviewed changes

elliott-with-the-longest-name-on-github added 3 commits March 13, 2026 16:05

LazyPromise

ec96caf

promise chain correction

b4b5c9b

better cleanup

72bc665

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat: `hydratable` and a more consistent remote functions model#15533

feat: `hydratable` and a more consistent remote functions model#15533
elliott-with-the-longest-name-on-github wants to merge 10 commits intomainfrom
elliott/remote-functions-hydratable-take-2

elliott-with-the-longest-name-on-github commented Mar 11, 2026 •

edited

Loading

Uh oh!

changeset-bot bot commented Mar 11, 2026 •

edited

Loading

Uh oh!

svelte-docs-bot bot commented Mar 11, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Rich-Harris Mar 13, 2026

Uh oh!

elliott-with-the-longest-name-on-github Mar 13, 2026

Uh oh!

Rich-Harris Mar 13, 2026

Uh oh!

Rich-Harris Mar 13, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		* Unlike awaiting the resource directly, this can be used anywhere
		* (load functions, event handlers, etc) without requiring a reactive context.

		start: () => get_response(__, arg, state, get_remote_function_result),
		refresh: () => get_remote_function_result()

	start: () => get_response(__, arg, state, get_remote_function_result),
	refresh: () => get_remote_function_result()
	get_remote_function_result

Uh oh!

Conversation

elliott-with-the-longest-name-on-github commented Mar 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

hydratable

New rules around query usage

Bugfixes

Uh oh!

changeset-bot bot commented Mar 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

⚠️ No Changeset found

Uh oh!

svelte-docs-bot bot commented Mar 11, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Rich-Harris Mar 13, 2026

Choose a reason for hiding this comment

Uh oh!

elliott-with-the-longest-name-on-github Mar 13, 2026

Choose a reason for hiding this comment

Uh oh!

Rich-Harris Mar 13, 2026

Choose a reason for hiding this comment

Uh oh!

Rich-Harris Mar 13, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

elliott-with-the-longest-name-on-github commented Mar 11, 2026 •

edited

Loading

`hydratable`

changeset-bot bot commented Mar 11, 2026 •

edited

Loading