Troubleshooting & Validation
Relevant source files
The following files were used as context for generating this wiki page:
- skills/svelte-effect-runtime/references/validation.md
- modules/svelte-effect-runtime/src/diagnostics.ts
- modules/svelte-effect-runtime/src/compiler.ts
- modules/svelte-effect-runtime/src/script-transform/runes.ts
- modules/svelte-effect-runtime-language-server/src/patch-language-server/transform-results.ts
- modules/svelte-effect-runtime/src/markup/transform/scan.ts
The Troubleshooting & Validation system in Svelte Effect Runtime (SER) ensures that effectful code, specifically yield* expressions and <script effect> blocks, are correctly implemented within Svelte components. Because SER introduces syntax that standard Svelte tooling (like svelte-check) might interpret as invalid, the project provides a dedicated suite of diagnostics, compiler guards, and language server patches to validate SER-specific source forms.
The system focuses on identifying "suspicious" usage of the Effect library within Svelte markup and scripts, ensuring that the SER Vite transform can correctly lower these expressions without breaking the standard Svelte contract.
Sources: skills/svelte-effect-runtime/references/validation.md:1-5, modules/svelte-effect-runtime/src/diagnostics.ts:1-35
Diagnostic Architecture
Validation is primarily handled through a Vite diagnostics plugin and specialized scanning functions. The system analyzes both Svelte markup expressions and script sections to ensure compliance with SER's transformation rules.
Markup Diagnostic Flow
The diagnostic engine scans Svelte markup for brace expressions and evaluates them based on several criteria:
- Effect Reference Detection: Identifying usage of
Effect.gen,Effect.promise, etc. - Yield Usage: Checking if effectful expressions are properly prefixed with
yield*. - Event Handler Context: Ensuring
yield*is used at the attribute boundary rather than hidden inside callbacks.
Key Diagnostic Functions
| Function | Description | Source |
|---|---|---|
find_svelte_effect_diagnostics | High-level entry point for scanning a component's markup for suspicious Effect usage. | diagnostics.ts:37-51 |
find_effect_local_names | Scans script regions to find local aliases for the Effect import to ensure accurate tracking. | diagnostics.ts:53-78 |
make_expression_diagnostics | Evaluates a specific brace expression against validation rules (e.g., bare Effect.gen, missing yield*). | diagnostics.ts:89-160 |
Compiler Guards and Plugin Validation
The Vite plugin effect() includes multiple sub-plugins dedicated to troubleshooting and validation during the build process.
Diagnostics Plugin
This plugin runs during the Vite transform hook. It filters for Svelte modules and applies the find_svelte_effect_diagnostics function. If issues are found, it emits a Vite warning including the file ID, message, and precise source location (line/column).
Sources: modules/svelte-effect-runtime/src/compiler.ts:80-120
Reserved Helper Guard
SER uses specific generated names like Dispatcher and Code in its lowered output. The make_reserved_helper_guard_plugin checks if a user has local bindings with these names, which would cause naming collisions during the SER transform.
Sources: modules/svelte-effect-runtime/src/compiler.ts:122-143
Plugin Ordering Notice
Since SER must lower its syntax before the standard Svelte compiler runs, plugin order is critical. The compiler logs an info notice if it detects plugins running before SER that might prematurely read or process .svelte files.
Sources: modules/svelte-effect-runtime/src/compiler.ts:153-172, modules/svelte-effect-runtime/src/compiler.ts:241-255
Rune and Script Validation
Validation extends into the Svelte 5 Rune system. The validate_rune_yield_usage function ensures that yield* only appears in positions that the script-effect transform can lower safely.
Prohibited Rune Usage
Certain runes or callback-based runes cannot contain top-level yield* because it would break the synchronous or reactive contract of Svelte.
- Prohibited:
$effect,$effect.pre,$effect.root,$derived.by(when containing top-levelyield*). - Allowed (Async-compatible):
$derived,$state,$state.raw,$bindable.
Sources: modules/svelte-effect-runtime/src/script-transform/runes.ts:10-44
Class Member Restrictions
yield* cannot be used inside class members (fields or methods). These are not considered top-level reactive work and must be moved to a script effect statement before assignment.
Sources: modules/svelte-effect-runtime/src/script-transform/index.ts:378-410
Common Troubleshooting Warnings
The following table summarizes common validation errors and warnings emitted by the system:
| Warning Type | Cause | Recommendation |
|---|---|---|
| Hidden Event Yield | yield* detected inside an arrow function/callback in an event handler. | Move yield* to the event attribute boundary: onclick={yield* save()}. |
| Explicit Runner | Using Effect.runPromise or similar inside markup. | Use yield* so SER can manage the Effect lifecycle and cancellation. |
| Bare Effect Gen | Using Effect.gen as a value instead of a program. | Use yield* Effect.gen(function* () { ... }). |
| Reserved Helper | Using local variables named Dispatcher or Code. | Rename or alias local bindings to avoid collisions with SER helpers. |
| Async Effect in Sync Rune | Using yield* inside a synchronous rune like $effect. | Use a supported async-compatible rune or move logic to a <script effect> block. |
Sources: modules/svelte-effect-runtime/src/diagnostics.ts:176-235, modules/svelte-effect-runtime/src/script-transform/runes.ts:46-56, modules/svelte-effect-runtime/src/compiler.ts:337-347
Language Server Boundary Validation
In editor environments, the language server must handle transform failures gracefully to prevent the Svelte server process from crashing.
Safe Transform Results
The safe_transform_result utility wraps runtime transforms in a try/catch block. If a transform fails (e.g., due to a syntax error in the effect block), it returns a TransformFailed tag along with a "diagnostic fallback result."
Sources: modules/svelte-effect-runtime-language-server/src/patch-language-server/transform-results.ts:74-98
Editor-Visible Diagnostics
When a script or markup transform fails in the editor, the system injects a TypeScript diagnostic statement into the virtual document. This makes the error visible to the developer within the IDE as a const __SER_language_server_transform_error: never assignment.
Sources: modules/svelte-effect-runtime-language-server/src/patch-language-server/transform-results.ts:133-176
Summary
Troubleshooting and validation in Svelte Effect Runtime are designed to bridge the gap between SER's effectful syntax and Svelte's standard expectations. By utilizing a combination of Vite diagnostics, AST-based rune validation, and language server error boundaries, the system provides clear feedback to developers while ensuring the stability of the compilation pipeline. Developers should prioritize validation that runs through the SER Vite transform (e.g., vite build or vitest) over generic tools like svelte-check.
Sources: skills/svelte-effect-runtime/references/validation.md:1-12