Remote Queries & Commands

Relevant source files

The following files were used as context for generating this wiki page:

• modules/svelte-effect-runtime/src/server/factories.ts
• modules/svelte-effect-runtime/src/server/types.ts
• modules/svelte-effect-runtime/src/compiler/remote-client.ts
• modules/svelte-effect-runtime/src/compiler.ts
• modules/svelte-effect-runtime/src/remote/client/form-transport.ts
• skills/svelte-effect-runtime/references/runtime-and-server.md

Remote Queries and Commands represent the bridge between the Svelte frontend and Effect-powered server logic. This system allows developers to define effectful server-side handlers that are automatically transformed into type-safe, Effect-aware client functions. By leveraging SvelteKit's experimental remote functions, the runtime enables seamless data fetching (Queries), mutations (Commands), and progressive form handling (Forms) while maintaining full compatibility with the Effect library's error handling and dependency injection.

These utilities are primarily consumed via <script effect> blocks in Svelte components, where developers can use yield* directly on remote calls to suspend execution until data is resolved or to handle side effects declaratively.
Sources: README.md:14-32, skills/svelte-effect-runtime/references/runtime-and-server.md:31-62, modules/svelte-effect-runtime/src/server/factories.ts:251-260

Server-Side Factories

The server-side implementation utilizes factory functions to wrap native SvelteKit remote handlers. These factories enforce input validation using either Effect.Schema or Standard Schema and provide the necessary context for Effect execution.

Remote Handler Types

Factory	Purpose	Input Validation	Returns
Query	Read-only data fetching. Supports batching and live streaming.	Schema / "unchecked"	EffectRemoteQuery
Command	Write-oriented mutations with pending state tracking.	Schema / "unchecked"	EffectRemoteCommand
Form	Progressive form submission with field-level validation.	Schema / "unchecked"	EffectRemoteForm
Prerender	Build-time or static data with dynamic fallback.	Schema / "unchecked"	EffectRemoteFunction

Sources: modules/svelte-effect-runtime/src/server/factories.ts:384-569, modules/svelte-effect-runtime/src/server/types.ts:252-329

Query System Architecture

The Query factory is polymorphic, supporting standard queries, batched queries for performance optimization, and live queries for real-time data streaming.

The query factory automatically attaches native SvelteKit resource methods such as refresh, set, and withOverride to the resulting Effect, allowing components to trigger revalidation or optimistic updates directly from the Effect object.
Sources: modules/svelte-effect-runtime/src/server/factories.ts:162-212, modules/svelte-effect-runtime/src/server/types.ts:413-424

Client-Side Adaptation

To enable the use of yield* in components, the SER compiler performs a post-processing step on SvelteKit's generated client remote modules. This transformation wraps native SvelteKit calls in adapters that return Effect types instead of standard Promises or SvelteKit resources.

Compiler Transformation Logic

The compiler identifies exports from modules ending in .remote.js and applies the rewrite_remote_client_exports function. This function injects necessary runtime imports and overwrites native exports with SER-specific adapters.

Form Transport & Validation

For Form actions, the runtime manages complex transport logic, including converting inputs to FormData and decoding specialized error envelopes that carry validation issues.

/** Example of form submission transport */
export async function submit_remote_form<Output>(
	form_obj: NativeFormRecord,
	input: unknown,
	decode_payload: (value: unknown) => unknown,
	remote_base: string,
	preflight_schema?: StandardSchema,
): Promise<Output> {
	const action_id = get_remote_action_id(form_obj);
	// ... preflight validation and fetch ...
	const response = await fetch(to_remote_form_url(remote_base, action_id), {
		method: "POST",
		body: to_form_data(input),
	});
	// ... decode response ...
}

Sources: modules/svelte-effect-runtime/src/remote/client/form-transport.ts:69-105

Execution Contexts

Remote handlers run within a specific ServerRuntime configured in the project's hooks.server.ts. This allows handlers to access shared services like database pools or authentication clients via Effect's dependency injection.

• Singleton Services: Defined in ServerRuntime.make() in src/hooks.server.ts.
• Request-Scoped Data: Accessed via RequestEvent inside the handler for cookies, params, and locals.
• Client Runtime: Browser-side services (storage, analytics) are initialized via ClientRuntime.make() in src/hooks.client.ts.

Sources: skills/svelte-effect-runtime/references/runtime-and-server.md:1-30

Conclusion

Remote Queries and Commands provide a unified interface for server interaction in Svelte Effect Runtime. By abstracting transport and validation logic into factory functions and automated compiler transforms, the system ensures that server-side effects remain type-safe and easily consumable within the reactive lifecycle of Svelte 5 components.