Introduction

Relevant source files

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

• README.md
• skills/svelte-effect-runtime/SKILL.md
• modules/svelte-effect-runtime/src/compiler.ts
• modules/svelte-effect-runtime/src/markup/transform/index.ts
• modules/svelte-effect-runtime/src/script-transform/index.ts
• skills/svelte-effect-runtime/references/syntax.md
• skills/svelte-effect-runtime/references/setup.md

Svelte Effect Runtime (SER) is a specialized framework enhancement for Svelte 5 that enables the direct use of Effect programs within Svelte components. It achieves this by providing a compile-time transform that allows developers to use yield* expressions directly in .svelte files—both within scripts and markup—preserving reactive intent without requiring manual lifecycle management or boilerplate wrappers like onMount. Sources: README.md:1-15, skills/svelte-effect-runtime/SKILL.md:1-10

The system architecture is comprised of a core runtime module, a Vite compiler plugin, and specialized editor tooling including a language server and VS Code extension. Together, these components lower SER-specific syntax into standard Svelte-compatible code that manages fiber cancellation and reactive dependency tracking. Sources: README.md:23-28, modules/svelte-effect-runtime/src/compiler.ts:55-65

Core Architecture and Pipeline

The SER system operates as a transformation layer that sits before the standard Svelte compiler. It identifies specific syntax markers, such as the effect attribute on <script> tags or yield* expressions in markup, and rewrites them into generated dispatcher events and runtime helper calls. Sources: modules/svelte-effect-runtime/src/markup/transform/index.ts:31-45, skills/svelte-effect-runtime/references/setup.md:28-35

Transformation Flow

The following diagram illustrates how a Svelte source file is processed by the SER Vite plugin before reaching the Svelte compiler.

The transformation pipeline scans for lexical facts, lowers top-level yield* statements into reactive blocks, and injects necessary runtime imports. Sources: modules/svelte-effect-runtime/src/compiler.ts:130-150, modules/svelte-effect-runtime/src/script-transform/index.ts:101-130

Key System Components

The project is organized into several distinct modules that handle different aspects of the effectful execution lifecycle. Sources: README.md:23-28, package.json:6-10

Component	Description	Primary Responsibility
svelte-effect-runtime	Core Runtime & Compiler	Houses the Vite plugin, script/markup transforms, and runtime dispatchers.
svelte-effect-runtime-grammars	Syntax Grammars	Provides TextMate and tree-sitter definitions for SER-aware editor highlighting.
svelte-effect-runtime-language-server	Language Server	Patches the standard Svelte language server to support virtual documents and SER syntax.
svelte-effect-runtime-vsix	VS Code Extension	Integrates the language server into the VS Code editor environment.

Sources: README.md:23-28, modules/svelte-effect-runtime/package.json:1-25

Transformation Modules

Script Transformation

The transform_script_effect function processes <script effect> blocks. It performs a multi-phase transformation:

1. Detection: Identifying existing imports and required runtime bindings.
2. Lowering: Converting top-level yield* statements into reactive $effect blocks or async declarations.
3. Injection: Adding generated imports for the dispatcher and Effect runtime.
4. Wiring: Appending the runtime program and lifecycle hooks.

Sources: modules/svelte-effect-runtime/src/script-transform/index.ts:47-150

Markup Transformation

The transform_markup_effect function handles {yield* expr} expressions within the HTML portion of a component. It utilizes a strategy of character scanning and placeholder injection to ensure that TypeScript-specific syntax within script blocks does not break the Svelte parser during the classification phase. Sources: modules/svelte-effect-runtime/src/markup/transform/index.ts:31-55

The markup transform classifies placeholders into contexts such as #each blocks, #await blocks, or event handlers before replacing them with dispatcher-aware code. Sources: modules/svelte-effect-runtime/src/markup/transform/index.ts:60-90

Setup and Configuration

Integration requires specific configurations in both vite.config.ts and svelte.config.js to ensure the transformation order is correct and experimental features are enabled. Sources: skills/svelte-effect-runtime/references/setup.md:1-25

/** Example Vite Configuration */
import { sveltekit } from "@sveltejs/kit/vite";
import { effect } from "svelte-effect-runtime";

export default defineConfig({
  plugins: [effect(), sveltekit()], // effect() MUST come before sveltekit()
});

Sources: skills/svelte-effect-runtime/references/setup.md:28-35, modules/svelte-effect-runtime/src/compiler.ts:55-65

Required Svelte Compiler Options

To support component-level yield*, the Svelte compiler must be configured with specific experimental flags:

• experimental.async: Set to true to enable async rendering for components.
• kit.experimental.remoteFunctions: Set to true when utilizing SER's remote function capabilities (Query, Command, etc.).

Sources: skills/svelte-effect-runtime/references/setup.md:8-25

Summary

The Svelte Effect Runtime provides a seamless bridge between the Effect ecosystem and Svelte 5's reactive model. By automating the transformation of generator-based syntax into managed fibers, it allows developers to write complex effectful logic directly within the component structure while maintaining robust cancellation and error handling. Sources: skills/svelte-effect-runtime/SKILL.md:1-20, skills/svelte-effect-runtime/references/syntax.md:1-10