sveltekit-remote-functions

SvelteKit Remote Functions

現在のステータス

Remote functions は SvelteKit 2.58 では実験的です。SvelteKit Vite プラグインを介して vite.config.ts で有効にすることをおすすめします。

import { sveltekit } from '@sveltejs/kit/vite';
import { defineConfig } from 'vite';

export default defineConfig({
	plugins: [
		sveltekit({
			experimental: { remoteFunctions: true },
			compilerOptions: { experimental: { async: true } } // only for await in components
		})
	]
});

クイックスタート

ファイル名： *.remote.ts または *.remote.js から remote functions をエクスポートします。 リモートファイルは、src/lib/server を除く src 配下のどこにでも配置できます。

どの関数を使うか？

• 動的な読み取り → query()
• サーバーのリアルタイムストリーム → query.live()
• プログレッシブフォーム → form()
• イベントハンドラーによる変更 → command()
• ビルド時／静的な読み取り → prerender()

例

// posts.remote.ts
import { command, query, requested } from "$app/server";
import * as v from "valibot";

export const getPosts = query(
	v.object({ tag: v.optional(v.string()) }),
	async (filter) => {
		return db.posts.find(filter);
	},
);

export const createPost = command(
	v.object({ title: v.string() }),
	async (data) => {
		await db.posts.create(data);

		for (const { query } of requested(getPosts, 5)) {
			void query.refresh();
		}
	},
);

クライアント：

<script lang="ts">
	import { createPost, getPosts } from './posts.remote';

	const posts = $derived(await getPosts({ tag: 'svelte' }));
</script>

<button onclick={() => createPost({ title: 'New' }).updates(getPosts)}>
	Create
</button>

現在のルール

• Kit 2 では引き続き svelte.config.js を使用できますが、Kit 3 では Vite プラグインから Kit の設定を読み取るようになります。
• Remote functions は、ブラウザーから呼び出された場合でも常にサーバー上で実行されます。
• 引数と戻り値には devalue が使用されます。関数、クラスインスタンス、シンボル、循環参照、RegExp は避けてください。
• 公開する入力は Standard Schema（valibot、zod、arktype など）で検証するか、意図を明確にしたうえで .unchecked／'unchecked' を使用してください。
• query.batch() は、n+1 の読み取りを解消するために、同じマクロタスクからの呼び出しをまとめます。
• query.live() は非同期イテラブルを返します。SSR では最初の値が使用され、クライアントはレンダリング中に接続を維持します。
• ミューテーションからリスナーに通知できる場合は、ポーリングよりイベント駆動型のライブクエリをおすすめします（Promise.withResolvers()／pubsub）。
• ライブクエリには connected と reconnect() がありますが、refresh() はありません。.run() は Promise<AsyncGenerator<T>> を返します。
• ライブクエリのレスポンスをサービスワーカーでキャッシュしないでください。Cache-Control: no-store のストリームは除外してください。
• form().enhance() の submit() は、送信が有効／成功した場合に true を、検証に失敗した場合に false を返します。
• .updates() はクライアントから要求される機能です。サーバーハンドラーでは requested(queryFn, limit) を使ってオプトインする必要があります。
• requested() は { arg, query } を返すようになりました。バインドされたインスタンスで query.refresh()／query.set(...) を呼び出してください。
• クライアントが制御する更新リクエストを制限するため、requested() には limit が必要です。
• command／form ハンドラー内では void query.refresh()／void query.set(value) を使用してください。更新の待機とシリアライズは SvelteKit が行います。
• ライブクエリでは、単一処理のミューテーションから void live_query.reconnect() を呼び出せます。
• プログレッシブエンハンスメントが重要な場合は、command() より form() をおすすめします。
• デプロイごとに最大 1 回しか変更されないデータには prerender() を使用してください。
• 最終確認日： 2026-06-08

参考ファイル

• references/remote-functions.md - 現在のパターン、例、注意点