Remote functions docs don't work

[mbanerjeepalmer]

Describe the bug

The docs don't work

Problem

The 'Remote functions' docs suffer from a few important problems:

1. They can't be run 'as-is'. They rely on a fictional 'db' module.
2. It's unclear how to set a variable value at the top level of a <script> tag. Perhaps it's obvious to smart people who understand Svelte, but it's not self-evident from the docs.
3. Indeed, a simplified version of the docs' example under 'Query arguments' yields an error.

<script lang="ts">
	import { getPost } from './data.remote';
	const post = await getPost();
</script>
<h1>{post.title}</h1>

\[500\] GET /
Svelte error: await\_outside\_boundary
Cannot await outside a \`<svelte:boundary>\` with a \`pending\` snippet
https://svelte.dev/e/await\_outside\_boundary
    at await\_outside\_boundary (node\_modules/svelte/src/internal/shared/errors.js:11:17)
    at \_page (src/routes/+page.svelte:4:12)
    at <anonymous> (.svelte-kit/generated/root.svelte:68:14)
    at \_layout (src/routes/+layout.svelte:9:18)

Diagnosis

I found the source of the YouTube demo. That repo has a boundary in its top-level +layout.svelte.

Uncomment from the +layout.svelte and below to see it work.

Proposal

1. The Remote functions docs should be self-contained. A user should be able to copy-paste and see it work.
2. To make it more readable, the docs should keep using the same example. Changing from getPost to getPosts doesn't seem necessary.
3. Therefore the docs should (a) simply use the code in the example below as data.remote.ts and (b) link to a minimal live SvelteLab example so that users can see it work.

Example

Example

Reproduction

SvelteLab example

Logs

System Info

(I'm running this on SvelteLab...)


  System:
    OS: Linux 5.0 undefined
    CPU: (8) x64 Intel(R) Core(TM) i9-9880H CPU @ 2.30GHz
    Memory: 0 Bytes / 0 Bytes
    Shell: 1.0 - /bin/jsh
  Binaries:
    Node: 20.19.1 - /usr/local/bin/node
    Yarn: 1.22.19 - /usr/local/bin/yarn
    npm: 10.8.2 - /usr/local/bin/npm
    pnpm: 8.15.6 - /usr/local/bin/pnpm
  npmPackages:
    @sveltejs/adapter-auto: ^3.0.0 => 3.3.1 
    @sveltejs/kit: ^2.5.27 => 2.39.0 
    @sveltejs/vite-plugin-svelte: ^5.0.0 => 5.1.1 
    svelte: ^5 => 5.38.10 
    vite: ^6.0.0 => 6.3.6

Severity

annoyance

Additional Information

@dummdidumm this is probably relevant to you. I'm happy to submit a PR if you agree with my diagnosis and proposal.

[dennisregalado]

this tripped me up when I first started using remote functions too

[teemingc]

2. It's unclear how to set a variable value at the top level of a <script> tag. Perhaps it's obvious to smart people who understand Svelte, but it's not self-evident from the docs.

Can you expand on this point? Which part of the docs makes it unclear?

3. Indeed, a simplified version of the docs' example under ['Query arguments'](https://svelte.dev/docs/kit/remote-functions#query-Query-arguments) yields an error.

<script lang="ts"> import { getPost } from './data.remote'; const post = await getPost(); </script>

{post.title}

\[500\] GET /
Svelte error: await\_outside\_boundary
Cannot await outside a \`<svelte:boundary>\` with a \`pending\` snippet
https://svelte.dev/e/await\_outside\_boundary
    at await\_outside\_boundary (node\_modules/svelte/src/internal/shared/errors.js:11:17)
    at \_page (src/routes/+page.svelte:4:12)
    at <anonymous> (.svelte-kit/generated/root.svelte:68:14)
    at \_layout (src/routes/+layout.svelte:9:18)

I've encountered this issue myself and have raised this to the team. My understanding is that this will not be an issue in the future once we've unlocked async SSR because the getPost function will run on the server itself rather than the client. This is the preferred solution so in the meantime, we have not introduced any root level boundary.

2. To make it more readable, the docs should keep using the same example. Changing from `getPost` to `getPosts` doesn't seem necessary.

This is a common pattern in the SvelteKit docs to introduce the idea of dynamic data based on parameters separately from the introduction of the data loading API itself. If we do make this change, it might be a good idea to apply this in other doc pages too.

3. Therefore the docs should (a) simply use the code in the example below as `data.remote.ts` and (b) link to a minimal live SvelteLab example so that users can see it work.

I imagine a proper example and tutorial will be set up once remote functions are no longer experimental. Something similar to https://svelte.dev/tutorial/kit/page-data