Overall System Architecture
Relevant source files
The following files were used as context for generating this wiki page:
- README.md
- modules/svelte-effect-runtime/src/compiler.ts
- modules/svelte-effect-runtime/src/compiler/source-scan.ts
- modules/svelte-effect-runtime/src/script-transform/index.ts
- modules/svelte-effect-runtime/src/markup/transform/index.ts
- modules/svelte-effect-runtime-language-server/src/patch-language-server/patches.ts
- skills/svelte-effect-runtime/SKILL.md
The Svelte Effect Runtime (SER) is a specialized toolset designed to integrate the Effect library deeply into the Svelte 5 framework. It allows developers to write effectful code using yield* directly within Svelte components—both in script blocks and markup—by providing a compile-time transformation layer that converts this high-level syntax into standard Svelte-compatible code and runtime dispatcher calls.
The system is structured as a monorepo consisting of a core runtime, a Vite compiler plugin, specialized grammars for tooling, and a language server to provide editor support. The architecture relies on intercepting the standard Svelte compilation pipeline to lower SER-specific syntax (like <script effect> and markup yield*) before the official Svelte compiler processes the files.
Sources: README.md:1-25, skills/svelte-effect-runtime/SKILL.md:1-15
Core Architectural Components
The system architecture is divided into four primary packages that handle the transformation, execution, and developer experience.
| Component | Description |
|---|---|
| Runtime & Compiler | The core module containing the Vite plugin, source scanners, and script/markup transformers. |
| Grammars | TextMate and tree-sitter definitions for highlighting yield* and SER attributes in editors. |
| Language Server | A patched version of the Svelte language server that understands virtual SER documents. |
| VSIX Extension | The VS Code integration that launches the language server for .svelte files. |
Sources: README.md:27-32, modules/svelte-effect-runtime/package.json:1-40
System Data Flow
The following diagram illustrates how a Svelte file containing SER syntax moves through the system from source to final execution.
The architecture ensures that the Svelte compiler never sees raw yield* expressions, which would otherwise cause parser errors.
Sources: modules/svelte-effect-runtime/src/compiler.ts:110-140, modules/svelte-effect-runtime/src/markup/transform/index.ts:50-100
Compiler and Transformation Pipeline
The transformation pipeline is triggered by the effect() Vite plugin. This plugin orchestrates several sub-plugins that handle different aspects of the build.
The Vite Plugin Suite
The effect() function returns an array of plugins:
- Diagnostics Plugin: Scans code for SER-specific errors and warnings.
- Reserved Helper Guard: Prevents users from using identifiers that SER needs for generated code (e.g.,
Dispatcher,Code). - Svelte Transform Plugin: The primary engine that calls the script and markup transformers.
- Server Rewrite Plugin: Rewrites imports to point to
svelte-effect-runtime/serverduring SSR. - Remote Client Wrapper: Wraps SvelteKit remote functions in Effect adapters.
Sources: modules/svelte-effect-runtime/src/compiler.ts:46-60, modules/svelte-effect-runtime/src/compiler.ts:205-230
Source Scanning
Before transformation, the system performs a SvelteEffectSourceScan to identify script regions, style blocks, and markup expressions. This allows the transformers to operate on specific ranges without breaking standard HTML or CSS.
Script Transformation Architecture
The transform_script_effect module processes <script effect> blocks. It operates in distinct phases to lower yield* into reactive declarations.
- Phase 1 (Import Detection): Checks for existing
effectorsvelteimports to avoid collisions. - Phase 2 (Lowering): Iterates through top-level statements. If a statement contains a top-level
yield*, it is "lowered" into a Svelte-compatible rendering declaration. - Phase 3 (Injection): Injects necessary runtime imports (e.g.,
get_dispatcher,Effect). - Phase 4 (Wiring): Appends the runtime program and lifecycle wiring to the end of the script.
Sources: modules/svelte-effect-runtime/src/script-transform/index.ts:47-150
Markup Transformation Logic
The transform_markup_effect module handles yield* inside HTML tags and Svelte blocks (like {#each} or {#if}).
Sanitization and Classification
Since Svelte's parser does not support yield*, the markup transformer uses a "sanitize-then-parse" strategy:
- Sanitization: Replaces all
{yield* ...}expressions with unique placeholders (e.g.,__SER___markup_placeholder_0). - AST Parsing: Parses the sanitized markup using the standard Svelte compiler AST to determine the context of each placeholder.
- Classification: Identifies if a placeholder is inside an event handler, a logic block, or a plain expression.
- Emission: Replaces the placeholders with calls to the SER dispatcher.
Sources: modules/svelte-effect-runtime/src/markup/transform/index.ts:55-90, modules/svelte-effect-runtime/src/markup/transform/scan.ts:40-100
Language Server Integration
The Language Server Architecture provides editor support by "patching" the standard svelte-language-server. This allows VS Code to provide diagnostics and completions for SER syntax that would normally be flagged as invalid.
The patching logic intercepts DocumentSnapshot.fromDocument to create a virtual document where yield* has been transformed, enabling the TypeScript engine to validate the code without seeing the illegal syntax.
Sources: modules/svelte-effect-runtime-language-server/src/patch-language-server/patches.ts:77-105, modules/svelte-effect-runtime-language-server/src/patch-language-server/virtual-document.ts:21-70
Summary
The Svelte Effect Runtime architecture acts as a transparent middleware for Svelte 5. It uses a sophisticated scanning and transformation engine to bridge the gap between Svelte's synchronous reactive model and Effect's generator-based asynchronous execution. By providing both build-time (Vite plugin) and design-time (patched Language Server) components, it ensures a seamless developer experience while maintaining full compatibility with the standard Svelte compiler.