Svelte Remote Functions

Key Features

• Type-safe - Full TypeScript support across client-server boundary
• Validated - Use Standard Schema libraries (Zod, Valibot, Arktype) for argument validation
• Serialization - Automatic handling of Date, Map, Set via devalue
• Progressive enhancement - Forms work without JavaScript
• Optimistic updates - Update UI immediately, revert on error
• Single-flight mutations - Efficient query refresh patterns
• N+1 prevention - Batch queries with query.batch()
• Isolated form instances - Multiple forms with form.for(id)

Quick Start Patterns

Data Fetching (Query)

// data.remote.ts
import { query } from '$app/server';
import { z } from 'zod';

export const getPosts = query(async () => {
    return await db.getAllPosts();
});

export const getPost = query(z.string(), async (slug) => {
    return await db.getPost(slug);
});

// Batch queries to prevent N+1 problems
export const getPostsBatch = query.batch(z.string(), async (slugs) => {
    const posts = await db.getPostsBySlug(slugs);
    return slugs.map((slug) => posts.find((p) => p.slug === slug));
});

<!-- +page.svelte -->
<script>
    import { getPosts } from './data.remote';
</script>

{#each await getPosts() as post}
    <div>{post.title}</div>
{/each}

Or using properties:

<script>
    import { getPosts } from './data.remote';

    const posts = getPosts();
</script>

{#if posts.loading}
    Loading...
{:else if posts.error}
    Error!
{:else}
    {#each posts.current as post}
        <div>{post.title}</div>
    {/each}
{/if}

Form Submission

// data.remote.ts
import { form } from '$app/server';
import { redirect } from '@sveltejs/kit';
import { z } from 'zod';

export const createPost = form(async (data) => {
    const title = data.get('title');
    // Sensitive fields (prefixed with _) are not sent back to client
    const password = data.get('_password');

    await db.insert(title);

    // Refresh queries that changed
    getPosts().refresh();

    redirect(303, '/posts');
});

// With validation schema
export const createUser = form(
    z.object({
        email: z.string().email(),
        username: z.string().min(3),
        _password: z.string().min(8) // Sensitive field
    }),
    async (data) => {
        await db.createUser(data);
        redirect(303, '/login');
    }
);

<!-- +page.svelte -->
<form {...createPost}>
    <input name="title" />
    <input name="_password" type="password" />
    <button>Create</button>
</form>

<!-- Multiple isolated form instances -->
{#each items as item}
    <form {...deleteItem.for(item.id)}>
        <button>Delete {item.name}</button>
    </form>
{/each}

Imperative Actions (Command)

// likes.remote.ts
import { command, query } from '$app/server';
import { z } from 'zod';

export const getLikes = query(z.string(), async (id) => {
    return await db.getLikes(id);
});

export const addLike = command(z.string(), async (id) => {
    await db.incrementLikes(id);
    getLikes(id).refresh();
});

<!-- +page.svelte -->
<script>
    import { addLike, getLikes } from './likes.remote';

    let { item } = $props();

    const likes = getLikes(item.id);
</script>

<button onclick={() => addLike(item.id)}>
    Like ({await likes})
</button>

Invalidation & Refresh Patterns

Manual Refresh

<script>
    import { getPosts } from './data.remote';

    const posts = getPosts();
</script>

<button onclick={() => posts.refresh()}> Refresh </button>

Automatic Refresh After Mutations

Default: All queries refresh after form/command (inefficient).

Better: Specify which queries to refresh (single-flight mutation) from the client.

Client-side Refresh

<form
    {...createPost.enhance(async ({ submit }) => {
        await submit().updates(getPosts()); // ← Specify queries
    })}
></form>

await addLike(id).updates(getLikes(id));

Optimistic Updates

<form
    {...addTodo.enhance(async ({ data, submit }) => {
        await submit().updates(getTodos().withOverride((todos) => [...todos, { text: data.get('text') }]));
    })}
></form>

The override applies immediately and reverts on error.

Common Workflows

Creating a Resource

1. Define query for fetching list and form for creation
2. In form handler, call query().refresh() before redirect
3. User sees updated list after redirect

Updating with Optimistic UI

1. Define query for data and command for update
2. Call command().updates(query().withOverride(...))
3. UI updates immediately, reverts on error

Form with Custom Logic

1. Use form.enhance() to customize submission
2. Access form data and submit function
3. Call submit().updates() for targeted refresh
4. Handle success/error states

Critical Syntax Rules

Function signatures:

• ✅ No args: query(async () => { })
• ✅ With args: query(z.schema(), async (arg) => { })
• ❌ NEVER: query(async ({}) => { }) or query(async (arg) => { }) without schema
• ❌ NEVER: query(z.schema(), async (arg, event) => { }) - use getRequestEvent() instead

Calling functions:

• ✅ getPosts() or getPost('slug')
• ❌ Missing required arguments: getPost()

Request context:

// ✅ DO
import { getRequestEvent } from '$app/server';

const { cookies, locals } = getRequestEvent();

// ❌ DON'T
async (id, event) => {}; // Never use event parameter

Validation

Always validate arguments using Standard Schema (Zod recommended):

import { z } from 'zod';

// Primitives: z.string(), z.number(), z.boolean()
query(z.string(), async (id) => {});

// Objects with sensitive fields (underscore prefix not sent back)
form(
    z.object({
        username: z.string(),
        _password: z.string().min(8)
    }),
    async (data) => {}
);

// Complex nested schemas
query(
    z.object({
        filters: z.object({
            status: z.enum(['active', 'archived']),
            limit: z.number().min(1).max(100)
        })
    }),
    async (params) => {}
);

Custom error handling in hooks.server.ts:

export function handleValidationError({ event, issues }) {
    return { message: 'Invalid request', code: 'VALIDATION_ERROR' };
}

Best Practices

1. Prefer query over prerender for dynamic data
2. Prefer form over command for better progressive enhancement
3. Use single-flight mutations instead of refreshing all queries
4. Validate all arguments with Standard Schema
5. Use optimistic updates for better perceived performance
6. Use client-side refresh for explicit control over query updates
7. Use query.batch() when fetching multiple items to prevent N+1 queries
8. Use form.for(id) when rendering multiple forms for isolated state
9. Prefix sensitive fields with underscore (_password, _apiKey) to prevent sending back to client

Important Notes

• Commands cannot be called during render
• Queries are cached: getX() === getX()
• Data serialized with devalue (Date, Map, Set supported)
• Sensitive fields (underscore-prefixed) never sent back to client
• Inside remote functions: RequestEvent differs (no params/route.id, url.pathname is /)
• Customize validation errors via handleValidationError in hooks.server.ts