Server Runtime Initialization

Server Runtime Initialization is the process of configuring and instantiating the long-lived server-side environment for Svelte Effect Runtime (SER). This initialization typically occurs within SvelteKit's src/hooks.server.ts file to provide persistent services—such as database pools, loggers, or authentication clients—to remote handlers like Queries and Commands.

The server runtime is distinct from the Client Runtime, which handles browser-side concerns like storage and client APIs. While the server runtime manages singleton services, request-scoped data (cookies, locals, params) is handled separately via the RequestEvent context within individual remote handlers.

Sources: skills/svelte-effect-runtime/references/runtime-and-server.md:15-30, modules/svelte-effect-runtime/src/mod.ts:10-25

Architecture and Components

The initialization process involves the ServerRuntime singleton and the Vite compiler plugin which ensures correct module routing.

Singleton Pattern

The ServerRuntime is a singleton export. In a standard SvelteKit environment, the Vite plugin automatically rewrites imports from svelte-effect-runtime to svelte-effect-runtime/server when they occur in server-side files (e.g., .server.ts, .remote.ts, or hooks.server.ts). This ensures that the specialized server implementation is used instead of the client-side stub.

Sources: modules/svelte-effect-runtime/src/mod.ts:55-68, modules/svelte-effect-runtime/src/compiler.ts:250-265

Component Relationship Diagram

The diagram shows how the ServerRuntime is initialized in server hooks and managed by the Vite plugin during the build process.

Sources: skills/svelte-effect-runtime/references/runtime-and-server.md:20-30, modules/svelte-effect-runtime/src/compiler.ts:285-295

Configuration and Setup

Initialization requires specific configurations in the Svelte and Vite environments to support the execution of effectful code and remote functions.

Required Settings

Sources: skills/svelte-effect-runtime/references/setup.md:5-30

Vite Plugin Initialization

The effect() plugin in compiler.ts orchestrates several sub-plugins during initialization to manage the server/client boundary.

The make_server_rewrite_plugin is critical for server runtime initialization as it scans files for imports of svelte-effect-runtime and replaces them with svelte-effect-runtime/server if the file is identified as a server runtime module.

Sources: modules/svelte-effect-runtime/src/compiler.ts:50-65, modules/svelte-effect-runtime/src/compiler.ts:240-255

Initialization Logic

The primary entry point for initialization is the ServerRuntime.make method.

Runtime Instantiation

In src/hooks.server.ts, the developer calls ServerRuntime.make(Layer) to build and cache the server-side dispatcher. If the server runtime is pure (no external services), the default empty runtime is used.

import { ServerRuntime } from "svelte-effect-runtime/server";
import { DatabaseLive } from "$lib/server/database";

export const init = () => {
  /** Initialize the runtime with a database layer */
  ServerRuntime.make(DatabaseLive);
};

Sources: skills/svelte-effect-runtime/references/runtime-and-server.md:20-30, modules/svelte-effect-runtime/src/mod.ts:55-68

Server Module Detection

The initialization system identifies "Server Runtime Modules" based on file naming conventions to determine where rewrite rules apply:

• Files ending in .server.ts, .server.js, .server.mts, or .server.cts.
• Files ending in .remote.ts, .remote.js, etc.
• The SvelteKit hooks.server.ts file.

Sources: modules/svelte-effect-runtime/src/compiler.ts:380-388

Summary

Server Runtime Initialization sets up the persistent Effect-based execution environment on the server. It relies on a combination of explicit initialization in hooks.server.ts and automated build-time import rewriting via the SER Vite plugin. This architecture ensures that server-only services are isolated from the client while remaining accessible to remote server functions.