Remote Functions #13986

dummdidumm · 2025-07-10T17:02:04Z

PR for #13897, discussion should happen there.

For a more complete commit history (with lots of explorations and dead ends; also includes some caching ideas) see #13957

Please don't delete this checklist! Before submitting the PR, please make sure you do the following:

It's really useful if your PR references an issue where it is discussed ahead of time. In many cases, features are absent for a reason. For large changes, please create an RFC: https://github.com/sveltejs/rfcs
This message body should clearly illustrate what problems it solves.
Ideally, include a test that fails without this PR but passes with it.

Tests

Run the tests with pnpm test and lint the project with pnpm lint and pnpm check

Changesets

If your PR makes a change that should be noted in one or more packages' changelogs, generate a changeset by running pnpm changeset and following the prompts. Changesets that add features should be minor and those that fix bugs should be patch. Please prefix changeset messages with feat:, fix:, or chore:.

* initial commit * various fixes * tweak demo * fix * remove acorn-typescript * simplify * fix * generate, don't transform * use an x- header * regenerate manifest when remote files are added/removed * move RPC logic out of page, it belongs elsewhere * use _app/remote/x * tighten up error handling * unused * CSRF * smaller payloads * belt and braces * don't use 204, that only applies to DELETE/PUT requests * turn remote_call into a factory - more compact and gives us a lot more options * analyze exports of remotes dynamically, add query/action/formAction as different types of remotes * update playground * POC: hydrate query results * remote form actions that hydrate and work without JS * conditional * load fn WIP * rerun query on invalidation * make it possible to call invalidate in rpc functions * fix * adjust form API * fix dev stale bug * let rpc partake in prerendering * prerender POC * cache POC * simplify server remote logic by leveraging ESM self imports * cleanup server remote info * rename functions + some docs * move more stuff into functions to deduplicate/cleanup/make connections clearer * prerendering * hide remote url, avoid unnecessary work * cache refinement * various fixes * tests * don't call prerender function at runtime, tweak tests * tweak * tweak caching behavior * remove cache function from public API for now * add experimental flag * remove load helper function for now * move file * add refreshAll, related to #13139 * adjust overrides signature * query/redirect/form-fail handling * adjust caching behavior to cache until query is removed * disallow non-remote-function exports from .remote files * bump dts-buddy to be able to generate types without bugs again * handle query redirect without going through error boundaries * harmonize refresh with override signature * fixes * resolve cyclic import dependency * prerender treeshaking * refine API * refresh from the server * adjust tests, fix * adjust prerender * reorder functions * make query eager on the client if in reactive context * implement current/error/pending * remove optimistic in favor of override callback * add validate * form.for(...) * tweak api around redirects; allow single flight mutation redirect * implement stacking override API * fixes * deduplicate remote calls on the server during full page visits * rework to use resource class, fix some bugs * ensure refresh/then resolve in order * microtask tweaking * fix * cleanse event for remote functions * implement `updates` and `withOverride` for command * implement `updates` and `withOverride` for form * cleanup * Prevent state_unsafe_mutation error * restrict to 0 or 1 argument, enforce validation * validation tests * tweak * comment out for the time being * remove validate function * lint * guard * bump Svelte version * silence type errors * Update packages/kit/src/runtime/app/server/remote.js Co-authored-by: Paolo Ricciuti <[email protected]> * fix * update playground --------- Co-authored-by: Dominic Gannaway <[email protected]> Co-authored-by: Rich Harris <[email protected]> Co-authored-by: Paolo Ricciuti <[email protected]>

changeset-bot · 2025-07-10T17:02:10Z

⚠️ No Changeset found

Latest commit: 4706f36

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

Rich-Harris

it's going to take a few passes to fully review this glorious beast, but here's a few notes to start with. also:

will need a changeset 😆
if you have a .remote.ts that imports query or whatever from $app/server, then at build time you'll get a 'Cannot import $app/server into client-side code' error rather than the more helpful remote-functions-specific error. Would be nice to be more specific here while not creating a breaking change for anyone that happens to have an existing .remote.ts file (in which case they would probably appreciate a warning that they'll definitely need to rename that file)

Also, I'll probably find the answer to this as I read on but didn't want to lose the thought: are we (de)serializing arguments to remote functions that are called directly on the server? On the one hand it's wasteful, on the other it would avoid a client/server discrepancy (e.g. a mutation being respected on the server but not on the client)

Absolutely pumped for this to land

packages/kit/src/core/postbuild/analyse.js

Rich-Harris · 2025-07-14T20:42:44Z

packages/kit/src/core/postbuild/prerender.js

+			void enqueue(
+				null,
+				config.paths.base + '/' + config.appDir + '/remote/' + remote_function.__.id
+			);


is this right? the absence of entries doesn't indicate that there's no argument

My first though was that if you have prerender with an argument but no entries then what are you prerendering? But if it happens as part of a page prerender then that's fine, so you're right, we gotta find a different indicator.

Rich-Harris · 2025-07-14T20:43:37Z

packages/kit/src/core/postbuild/prerender.js

+		// /prerender/dependencies like indirect calls due to page prerenders?
+		// Does it really matter?
+		if (remote_function.__.entries) {
+			for (const entry of await remote_function.__.entries()) {


am wondering if entries is the right terminology to use here — we're using it because that's what it is for pages today, but in this context I wonder if arguments or something might be clearer

arguments as not that much clearer to me compared to entries, and entries is already for page prerendering, and since it's the same concept it felt better to also use the same name

I almost think that's more reason to call it something else, as it's helpful to be able to distinguish between them. 'Entries' specifically means entry points for the crawler, which is almost the opposite concept — in one case you're describing the start of the process ('start at blog/one, blog/two and blog/three and see what you can find'), in the other you're describing the end ('the user is going to need this data so I'm just going to tell you about it up-front').

What about data?

data is too generic IMO. What about another very generic name: inputs

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

Rich-Harris · 2025-07-14T21:03:40Z

packages/kit/src/exports/vite/build/build_remote.js

+ * @param {string} hashed_id 
+ * @param {string} remote_file_path 
+ */
+export function enhance_remotes(hashed_id, remote_file_path) {


could this be turned into a helper function rather than being inlined into every facade module? i.e. something like this:

import * as $$_self_$$ from './${sibling_file_name}'; import $$_enhance_remote_functions_$$ from '__sveltekit/remotes'; $$_enhance_remote_functions_$$($$_self_$$, ${s(hashed_id)}, ${s(remote_file_path)}); export * from './${sibling_file_name}';

packages/kit/src/exports/vite/index.js

Rich-Harris · 2025-07-14T21:10:30Z

packages/kit/src/exports/vite/index.js

+							dedent`
+						// Auto-generated part, do not edit
+						import * as $$_self_$$ from './${path.basename(id)}';
+						${enhance_remotes(hashed_id, id)}


see prior comment about helperifying this

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

Rich-Harris · 2025-07-14T21:49:23Z

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

+			return result;
+		})();
+
+		promise.refresh = async () => {


surely this shouldn't be allowed? the output of a prerender function is immutable

You're right we should treat it as immutable - corresponding code on the client still missing, will implement that soon.

Rich-Harris · 2025-07-14T21:50:35Z

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

+		const promise = Promise.resolve(run_remote_function(event, true, arg, validate, fn));
+		// @ts-expect-error
+		promise.updates = () => {
+			throw new Error('Cannot call `command(...).updates(...)` on the server');


would be good if this used the actual name of the command (which could maybe be added to __?)

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

Rich-Harris · 2025-07-14T21:59:45Z

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

+		Object.defineProperty(wrapper, 'enhance', {
+			value: () => {
+				return { action: wrapper.action, method: wrapper.method, onsubmit: wrapper.onsubmit };
+			},
+			writable: false,
+			enumerable: false,
+			configurable: false
+		});


writable, enumerable and configurable all default to false, so they don't actually need to be specified. I think something like this would be more readable?

Object.defineProperties(wrapper, { __: { value: { type: 'form', // ... } }, enhance: { value: () => ({ ...wrapper }) }, formAction: { value: { ... } }, // ... });

removal of boolean is a good callout. I did it as separate defineProperty because TS is smart enough to enhance the type of wrapper in that case, with defineProperties it's not sadly

packages/kit/src/runtime/client/remote.svelte.js

documentation/docs/30-advanced/20-hooks.md

Rich-Harris · 2025-07-17T12:49:22Z

documentation/docs/30-advanced/20-hooks.md

+export const handleValidationError = ({ result }) => {
+  return { message: 'Schema Error', validationErrors: z.treeifyError(result.error)};
+}


per above, we will need to rethink this example

It works, we just need to pass result instead of result.error (it will give you a type error I think but it works; will open an issue over at Zod.

Rich-Harris · 2025-07-17T12:51:26Z

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

+export type HandleValidationError<
+	Result extends { issues: StandardSchemaV1.Issue[] } = { issues: StandardSchemaV1.Issue[] }
+> = (input: { result: Result; event: RequestEvent }) => MaybePromise<App.Error>;


see prior comment — no point nesting issues inside result IMHO

Suggested change

export type HandleValidationError<

Result extends { issues: StandardSchemaV1.Issue[] } = { issues: StandardSchemaV1.Issue[] }

> = (input: { result: Result; event: RequestEvent }) => MaybePromise<App.Error>;

export type HandleValidationError<

Issue extends StandardSchemaV1.Issue = StandardSchemaV1.Issue

> = (input: { issues: Issue[]; event: RequestEvent }) => MaybePromise<App.Error>;

Theoretically it can be enhanced later by standard schema to have other properties so I'd rather be on the safe side and pass the whole object in.

Rich-Harris · 2025-07-17T12:52:16Z

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

+							error(
+								400,
+								await remoteInfo.handleValidationError({
+									result,


Suggested change

result,

issues: result.issues,

Rich-Harris · 2025-07-17T12:53:02Z

packages/kit/test/apps/basics/src/hooks.server.js

+export const handleValidationError = ({ event, result }) => {
+	return { message: result.issues[0].message };


Suggested change

export const handleValidationError = ({ event, result }) => {

return { message: result.issues[0].message };

export const handleValidationError = ({ issues }) => {

return { message: issues[0].message };

Rich-Harris · 2025-07-17T13:01:20Z

packages/kit/src/core/postbuild/analyse.js

+		const exports = new Map();
+		for (const [name, value] of Object.entries(modules)) {
+			const type = /** @type {import('types').RemoteInfo} */ (value.__)?.type;
+			if (!type) continue;


If a .remote.ts file exports something like export lol = null then this fails cryptically:

Cannot read properties of null (reading '__')

I don't know if it's possible to restructure things such that we can reuse the logic in enhance_remotes (IIUC that needs this to run first) — maybe we need to duplicate stuff — but it would be nice to have a consistent 'lol is not a remote function' error

Also, by deferring the check until later, this is the error I see:

Error: Invalid export from remote file /Users/rich/Development/SVELTE/KIT/kit/playgrounds/basic/.svelte-kit/output/server/remote/5mmnej.js: blah is not a remote function. Can only export remote functions from a .remote file

We could use path.relative(cwd, file) as we do elsewhere and it would become this...

Error: Invalid export from remote file .svelte-kit/output/server/remote/5mmnej.js: blah is not a remote function. Can only export remote functions from a .remote file

...but that still doesn't really help me — what the user needs to see is something like this:

Error: blah exported from src/lib/todos.remote.ts is invalid — all exports from this file must be remote functions

Rich-Harris · 2025-07-17T13:17:47Z

packages/kit/src/core/postbuild/prerender.js

+		// /prerender/dependencies like indirect calls due to page prerenders?
+		// Does it really matter?
+		if (remote_function.__.entries) {
+			for (const entry of await remote_function.__.entries()) {


I almost think that's more reason to call it something else, as it's helpful to be able to distinguish between them. 'Entries' specifically means entry points for the crawler, which is almost the opposite concept — in one case you're describing the start of the process ('start at blog/one, blog/two and blog/three and see what you can find'), in the other you're describing the end ('the user is going to need this data so I'm just going to tell you about it up-front').

What about data?

Rich-Harris · 2025-07-17T13:19:17Z

packages/kit/src/core/postbuild/prerender.js

+		// TODO this writes to /prerender/pages/... eventually, should it go into
+		// /prerender/dependencies like indirect calls due to page prerenders?
+		// Does it really matter?


The separation is at best helpful and at worst harmless, though I would opt for prerender/data

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

Co-authored-by: Rich Harris <[email protected]>

sveltejs locked as too heated and limited conversation to collaborators Jul 10, 2025

dummdidumm added 5 commits July 10, 2025 19:30

Merge branch 'main' into remote-functions

47e995a

cleanup

91b94c0

remove cache code for now

731cbce

handleValidationError

e4134ee

error property

75b33a0

Rich-Harris reviewed Jul 14, 2025

View reviewed changes

Rich-Harris reviewed Jul 15, 2025

View reviewed changes

dummdidumm added 3 commits July 15, 2025 12:07

code review

b8c0026

tweak / simplify

902e228

Merge branch 'main' into remote-functions

5e48a48

Rich-Harris reviewed Jul 17, 2025

View reviewed changes

packages/kit/src/exports/public.d.ts Outdated Show resolved Hide resolved

Rich-Harris and others added 8 commits July 17, 2025 11:00

merge main

351512c

Apply suggestions from code review

5e3fc90

Co-authored-by: Rich Harris <[email protected]>

fix

729c7a2

fix params prop on leaf component

73b6f1b

refresh queries after goto with invalidateAll

88d4118

fix redirect logic

fc90222

revert overrides on error

f25299b

work around Svelte bug

fc2869b

		export const handleValidationError = ({ event, result }) => {
		return { message: result.issues[0].message };

Uh oh!

Remote Functions #13986

Are you sure you want to change the base?

Remote Functions #13986

Conversation

dummdidumm commented Jul 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Please don't delete this checklist! Before submitting the PR, please make sure you do the following:

Tests

Changesets

Uh oh!

changeset-bot bot commented Jul 10, 2025

⚠️ No Changeset found

Uh oh!

Rich-Harris left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dummdidumm Jul 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dummdidumm Jul 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

dummdidumm commented Jul 10, 2025 •

edited

Loading

dummdidumm Jul 15, 2025 •

edited

Loading

dummdidumm Jul 17, 2025 •

edited

Loading