Client Runtime Services

Relevant source files

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

• skills/svelte-effect-runtime/references/runtime-and-server.md
• modules/svelte-effect-runtime/src/compiler.ts
• modules/svelte-effect-runtime/src/script-transform/index.ts
• modules/svelte-effect-runtime/src/compiler/source-scan.ts
• modules/svelte-effect-runtime/src/markup/transform/index.ts
• AGENTS.md

The Client Runtime Services provide the infrastructure required to execute effectful code within a Svelte 5 application. While Svelte handles the UI and reactivity, the Client Runtime manages the lifecycle of Effect fibers, ensuring they are correctly wired into $state bindings and automatically cancelled when components unmount.

This system bridges the gap between the functional effect system and Svelte's reactive model. It allows developers to use yield* directly in component scripts and markup, which is then lowered into dispatcher-managed operations that interface with the browser-side runtime environment.

Sources: skills/svelte-effect-runtime/references/runtime-and-server.md:1-5, modules/svelte-effect-runtime/src/script-transform/index.ts:40-48, AGENTS.md:143-155

Architecture and Lifecycle

The client-side architecture revolves around a ClientRuntime that hosts browser-specific services. By default, an empty runtime is provided, but it can be extended in src/hooks.client.ts to include services like storage, analytics, and client APIs.

Component Initialization

During the component lifecycle, the ClientRuntime is initialized via hooks.client.ts. This is where the application provides live implementations of services that component effects might require.

import { ClientRuntime } from "svelte-effect-runtime";
import { BrowserStorageLive } from "$lib/services/browser-storage";

export const init = () => {
  ClientRuntime.make(BrowserStorageLive);
};

Sources: skills/svelte-effect-runtime/references/runtime-and-server.md:16-23

Key Components

The Dispatcher

The Dispatcher is a central internal service used by generated code to manage reactive effects. It provides methods like value to wire fiber results into $state bindings and handles HMR survival and cache lookups.

Feature	Description
Fiber Management	Automatically cancels fibers when reactive dependencies change or components unmount.
Reactive Binding	Wires the result of a completed fiber into a Svelte $state proxy.
HMR Support	Uses stable identifiers to ensure effects survive Hot Module Replacement.
Cache Lookups	Caches results based on ID and dependency combinations.

Sources: AGENTS.md:143-160, modules/svelte-effect-runtime/src/script-transform/index.ts:87-95

Transform Engine

The runtime services rely on a compile-time transform that prepares the component for effectful execution. This transform targets both script blocks and markup.

1. Script Transform: Lowers top-level yield* in <script effect> into dispatcher-managed blocks.
2. Markup Transform: Converts {yield* expr} in HTML templates into generated dispatcher events.
3. Vite Integration: The effect() plugin in vite.config.ts orchestrates these transforms and handles server/client environment boundaries.

Sources: modules/svelte-effect-runtime/src/compiler.ts:50-58, modules/svelte-effect-runtime/src/script-transform/index.ts:40-48, modules/svelte-effect-runtime/src/markup/transform/index.ts:44-55

Service Integration and Requirements

Client-side effects are distinct from server-side effects. While the server runtime handles database pools and auth clients, the client runtime is focused on browser APIs.

Client vs. Server Runtime

Characteristic	Client Runtime	Server Runtime
Host Environment	Browser	Node.js / Serverless
Typical Services	LocalStorage, Clocks, Geolocation	DB Pools, Queues, Loggers
Lifecycle	Component-bound / User Session	Long-lived / Process-bound
Entry Point	src/hooks.client.ts	src/hooks.server.ts

Technical Implementation Details

The runtime services are enabled by the effect Vite plugin, which applies several internal plugins to manage the environment:

• Diagnostics Plugin: Scans for suspicious Effect usage (e.g., explicit runners inside markup).
• Transform Plugin: Executes transform_svelte_effect with the target set to "client".
• Remote Client Wrapper: Wraps SvelteKit's generated client remote exports in Effect-returning adapters.

Sources: modules/svelte-effect-runtime/src/compiler.ts:50-58, modules/svelte-effect-runtime/src/compiler.ts:89-105

The ScriptTransformResult includes the transformed code and a map of relocations used by the language server to map generated runtime code back to the original source positions.

Sources: modules/svelte-effect-runtime/src/script-transform/index.ts:160-170, modules/svelte-effect-runtime/src/compiler/source-scan.ts:12-25

Conclusion

Client Runtime Services enable a seamless integration of the Effect ecosystem into Svelte components. By managing fiber lifecycles, service injection, and reactive state updates, the runtime allows developers to use a declarative yield* syntax for complex asynchronous and effectful logic without manual subscription management or boilerplate lifecycle hooks.

Sources: skills/svelte-effect-runtime/references/runtime-and-server.md:1-5, AGENTS.md:143-155