VS Code Extension (VSIX)
Relevant source files
The following files were used as context for generating this wiki page:
The Svelte Effect Runtime (SER) VS Code extension is the primary editor interface for providing IntelliSense, diagnostics, and syntax support for SER-enhanced Svelte files. Its core responsibility is to install and launch the SER Language Server Protocol (LSP) from the npm registry, ensuring that the specialized yield* syntax and <script effect> blocks are correctly interpreted by the editor.
The extension is designed to work harmoniously with the official Svelte extension. In its "auto" mode, it attempts to hook into the official Svelte extension to avoid running redundant language server instances, while still providing a fallback standalone client when the official extension is absent.
Sources: modules/svelte-effect-runtime-vsix/package.json, modules/svelte-effect-runtime-vsix/README.md
Architecture and Language Client Strategy
The extension manages the lifecycle of the svelte-effect-runtime-language-server. It supports multiple connection strategies to provide the best user experience depending on the environment.
Client Launch Flow
The following diagram illustrates how the extension decides to launch the language client based on user configuration and the presence of the official Svelte extension.
The extension supports .svelte and .sv file extensions and activates when a workspace contains these files or when specific commands are invoked.
Sources: modules/svelte-effect-runtime-vsix/package.json:57-128, modules/svelte-effect-runtime-vsix/README.md
Language Server Integration
The extension leverages vscode-languageclient to communicate with the server. The server itself is a patched version of the standard Svelte language server, modified to handle SER-specific features like virtual document mapping for yield* expressions.
Sources: modules/svelte-effect-runtime-vsix/package.json:44, modules/svelte-effect-runtime-language-server/src/patch-language-server/patches.ts
Extension Configuration
The extension provides several configuration options to control the language server behavior and pathing.
| Property | Type | Default | Description |
|---|---|---|---|
svelte-effect-runtime.languageServer.enabled | boolean | true | Automatically starts the LSP for .svelte and .sv files. |
svelte-effect-runtime.languageServer.client | string | "auto" | Selection between auto, direct, or svelteExtension strategies. |
svelte-effect-runtime.languageServer.path | string | "" | Absolute path to a custom server script; triggers npm install if empty. |
Sources: modules/svelte-effect-runtime-vsix/package.json:88-120
Commands
The extension contributes several commands to the VS Code command palette for manual server management and debugging.
| Command | Title |
|---|---|
svelte-effect-runtime.startLanguageServer | Start Language Server |
svelte-effect-runtime.stopLanguageServer | Stop Language Server |
svelte-effect-runtime.restartLanguageServer | Restart Language Server |
svelte-effect-runtime.showOutput | Show Output |
Sources: modules/svelte-effect-runtime-vsix/package.json:69-86
Language Server Patching Logic
The extension's primary value is provided via the language server it launches. This server applies several critical patches to the standard Svelte/TypeScript environment to support SER syntax without reporting false-positive errors.
Virtual Document Projection
The server creates "virtual documents" where SER-specific syntax is transformed into valid TypeScript before being handed to the TypeScript language service. This allows features like "Go to Definition" and "Hover" to work on yield* expressions.
Key Patch Points
The server intercepts several internal Svelte processes to inject SER logic:
- File Extension Patching: Maps
.sveltefiles to virtual.d.svelte.tspaths so TypeScript recognizes them as source modules. - Compiler Options: Automatically enables
experimental.async: truein the Svelte compiler options to support component-levelyield. - Document Mappers: Uses
SequentialDocumentMapperto translate positions between the user's SER source and the generated virtual TypeScript.
Sources: modules/svelte-effect-runtime-language-server/src/patch-language-server/patches.ts:25-46, modules/svelte-effect-runtime-language-server/src/patch-language-server/virtual-document.ts:114-122, modules/svelte-effect-runtime-language-server/src/patch-language-server/patches.ts:311-335
Build and Release Process
The VSIX package is built using a workspace-wide build script. All SER packages must maintain synchronized version numbers.
# Build the extension from the workspace root
corepack pnpm run build:extension
# Create the .vsix package
corepack pnpm run package:extension
The build process involves cleaning the directory, running a specialized extension builder (build/ext.ts), and then packaging with build/vsix.ts.
Sources: package.json:8-11, modules/svelte-effect-runtime-vsix/package.json:37-41, AGENTS.md:189-204
Summary
The VS Code Extension serves as the bridge between the Svelte Effect Runtime syntax and the developer's editor. By launching a patched language server and managing virtual document projections, it enables a seamless development experience for effectful Svelte applications, providing standard IDE features for non-standard syntax.