Client/Server Data Exchange

Relevant source files

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

• modules/svelte-effect-runtime/src/internal/remote-server.ts
• modules/svelte-effect-runtime/src/internal/remote-client.ts
• modules/svelte-effect-runtime/src/remote/shared.ts
• modules/svelte-effect-runtime/src/compiler.ts
• modules/svelte-effect-runtime/src/compiler/remote-client.ts
• skills/svelte-effect-runtime/references/runtime-and-server.md

Client/Server Data Exchange in Svelte Effect Runtime (SER) provides a seamless bridge between SvelteKit frontend components and Effect-based server logic. It enables components to execute server-side functions—such as Queries, Commands, and Forms—using yield* syntax, while maintaining robust error handling and type safety across the network boundary. Sources: README.md, skills/svelte-effect-runtime/references/runtime-and-server.md:1-5

The system relies on a specialized compilation phase that transforms standard SvelteKit remote exports into Effect-aware adapters. These adapters manage the serialization of data, the translation of HTTP failures into structured Effect errors, and the lifecycle of server requests. Sources: modules/svelte-effect-runtime/src/compiler.ts:258-278, modules/svelte-effect-runtime/src/compiler/remote-client.ts:60-75

Remote Function Architecture

SER categorizes data exchange into specific functional types, each optimized for different interaction patterns. These are built using handlers imported from svelte-effect-runtime/server. Sources: skills/svelte-effect-runtime/references/runtime-and-server.md:32-40

Function Type	Purpose	Use Case
Query	Server-side reads	Fetching data for display (e.g., get_user).
Query.batch	Batch discovery	Aggregating multiple small reads during a single render.
Query.live	Streamed data	Real-time updates or server-sent events.
Command	Mutations	Actions triggered by UI events (e.g., save_settings).
Form	Form Handling	Progressive enhancement with validation support.
Prerender	Static data	Build-time data with optional dynamic fallbacks.

Sources: skills/svelte-effect-runtime/references/runtime-and-server.md:34-40

Remote Request Lifecycle

When a component calls a remote function using yield*, the data flows through several layers of transformation before reaching the server.

The client adapter wraps native SvelteKit remote calls to ensure that server responses are correctly interpreted as Effect results. Sources: modules/svelte-effect-runtime/src/compiler/remote-client.ts:88-100, modules/svelte-effect-runtime/src/internal/remote-client.ts

Transport and Error Protocol

SER uses a specialized error protocol to distinguish between domain-specific errors (e.g., "User Not Found") and transport-level failures (e.g., "404 Not Found" or Network Offline). Sources: modules/svelte-effect-runtime/src/remote/shared.ts:10-18

Structured Error Envelopes

The server wraps domain errors in a serialized envelope before sending them over the wire. This is identified by a well-known marker: __svelte_effect_remote__. Sources: modules/svelte-effect-runtime/src/remote/shared.ts:31-33

export interface SerializedRemoteFailureEnvelope {
	readonly __svelte_effect_remote__: true;
	readonly encoded: string;
}

Sources: modules/svelte-effect-runtime/src/remote/shared.ts:162-165

Error Classification

Errors are categorized into several types to allow for precise recovery logic in the UI:

• RemoteValidationError: High-level validation failures, typically from Form handlers.
• RemoteHttpError: Standard HTTP status failures (4xx, 5xx) thrown via SvelteKit's error() helper.
• RemoteTransportError: Failures during the fetch process or data decoding.
• Domain Errors: Custom errors defined in the Effect program's error channel.

Sources: modules/svelte-effect-runtime/src/remote/shared.ts:114-154

Compiler Transformations

The data exchange system depends on the remote-client compiler plugin. This plugin identifies imports from __sveltekit/remote and rewrites the generated client-side exports into adapters. Sources: modules/svelte-effect-runtime/src/compiler.ts:258-278

Adapter Generation

The compiler rewrites standard declarations to use specialized adapter factories:

• create_remote_query_adapter: For standard queries.
• create_remote_command_adapter: For mutations.
• create_remote_form_adapter: For form-based interactions, including base path handling for progressive enhancement.

Sources: modules/svelte-effect-runtime/src/compiler/remote-client.ts:88-102

Server and Client Runtimes

Data exchange requires initialized runtimes on both sides of the boundary to provide necessary services (e.g., databases on the server, storage on the client). Sources: skills/svelte-effect-runtime/references/runtime-and-server.md:1-25

• ClientRuntime: Configured in src/hooks.client.ts to provide browser-side services.
• ServerRuntime: Configured in src/hooks.server.ts to provide long-lived server dependencies like database pools.
• RequestEvent: Used inside remote handlers to access request-specific context like cookies or locals without polluting the singleton server services.

Sources: skills/svelte-effect-runtime/references/runtime-and-server.md:7-27

Summary

The Client/Server Data Exchange system in SER provides a robust, type-safe mechanism for Svelte components to interact with server-side Effect programs. By utilizing a custom transport protocol and automated compiler transformations, it abstracts the complexities of network serialization and error mapping, allowing developers to treat remote server calls as simple yield* operations within their components. Sources: README.md, modules/svelte-effect-runtime/src/compiler/remote-client.ts