Language Server Internals
Relevant source files
The following files were used as context for generating this wiki page:
- modules/svelte-effect-runtime-language-server/src/server.ts
- modules/svelte-effect-runtime-language-server/src/patch-language-server/index.ts
- modules/svelte-effect-runtime-language-server/src/patch-language-server/svelte-internals.ts
- modules/svelte-effect-runtime-language-server/src/patch-language-server/virtual-document.ts
- modules/svelte-effect-runtime-language-server/src/patch-language-server/types.ts
- modules/svelte-effect-runtime-language-server/package.json
- modules/svelte-effect-runtime/src/compiler/source-scan.ts
The Svelte Effect Runtime (SER) Language Server is a specialized extension of the standard svelte-language-server. Its primary purpose is to provide editor support for SER-specific syntax, such as <script effect> and yield* expressions in markup, which would otherwise be flagged as errors by standard Svelte tooling. It achieves this by patching the official Svelte language server at runtime and projecting SER source code into a format compatible with standard TypeScript and Svelte analyzers.
Sources: modules/svelte-effect-runtime-language-server/src/server.ts:16-25, modules/svelte-effect-runtime-language-server/package.json:2-3, skills/svelte-effect-runtime/SKILL.md:29-32
Architecture and Bootstrapping
The server operates as a Node.js process using a JSON-RPC connection over stdio or IPC. The core logic involves a "bootstrap" phase where the server intercepts and patches internal classes of the svelte-language-server.
Server Initialization Flow
The server starts by invoking bootstrap_language_server(), which loads the SER runtime transformation modules and applies patches to the Svelte compiler and TypeScript snapshot paths. Once patched, it hands control to the standard startServer from svelte-language-server.
The diagram above shows the sequential initialization of the language server, ensuring SER transforms are active before any files are processed.
Sources: modules/svelte-effect-runtime-language-server/src/server.ts:16-25, modules/svelte-effect-runtime-language-server/src/patch-language-server/index.ts:11-37
Connection Patching
The server specifically patches the LSP connection to handle textDocument/diagnostic requests. If a diagnostic handler returns null, it ensures a valid "full" diagnostic item is returned to prevent editor errors.
Sources: modules/svelte-effect-runtime-language-server/src/server.ts:47-75
Virtual Document Projection
To support SER syntax in editors, the server creates "virtual documents." These are projections where SER-specific code is transformed into standard code that TypeScript and Svelte can understand, while maintaining a mapping back to the original source.
Transformation Pipeline
The prepare_virtual_document function coordinates several transformation steps:
- Source Scanning: Lexical analysis of the Svelte file to find script regions and markup expressions.
- Normalization: Converting bare
{const ...}tags into{@const ...}to satisfy Svelte parser requirements. - Global Script Injection: Adding
lang="ts"to scripts that lack it to ensure consistent TypeScript analysis. - SER Transform: Applying
transformEffectMarkupandtransformEffectScriptto loweryield*andeffectattributes.
The diagram illustrates the transformation pipeline used to generate a virtual document from raw SER source.
Sources: modules/svelte-effect-runtime-language-server/src/patch-language-server/virtual-document.ts:17-101, modules/svelte-effect-runtime/src/compiler/source-scan.ts:153-176
Document Mappers
Because the virtual document modifies the original source, the server uses SequentialDocumentMapper to translate positions (line/character) between the generated code and the user's view. This ensures features like "Go to Definition" or "Hover" work correctly.
| Mapper Type | Purpose |
|---|---|
scriptMapper | Maps transformed <script effect> content back to original locations. |
markupMapper | Maps lowered markup yield* expressions. |
globalTypescriptMapper | Handles offsets shifted by injecting lang="ts". |
normalizationMapper | Handles offsets shifted by normalizing const to @const. |
Sources: modules/svelte-effect-runtime-language-server/src/patch-language-server/virtual-document.ts:108-115, modules/svelte-effect-runtime-language-server/src/patch-language-server/types.ts:24-33
Internal Patching Mechanism
The server relies on svelte-internals.ts to dynamically require internal modules from the svelte-language-server installation. This allows it to wrap and extend private APIs without forking the entire project.
Patched Components
The server intercepts the following Svelte/TypeScript integration points:
- DocumentSnapshot: Used to mark a document as "patched" via a
Symbol. - TypeScript Snapshot Path: Replaced to apply SER transforms whenever the TypeScript service requests file content.
- Svelte Compiler Path: Updated to use
transform_svelte_effectinstead of the standard Svelte compiler for internal processing.
Sources: modules/svelte-effect-runtime-language-server/src/patch-language-server/svelte-internals.ts:15-45, modules/svelte-effect-runtime-language-server/src/patch-language-server/index.ts:11-14
Data Structures
The system uses specific types to track relocations and transformations:
export type Relocation = {
originalStart: number;
originalEnd: number;
generatedStart: number;
generatedEnd: number;
};
export type TransformResult = {
code: string;
map?: Record<string, unknown>;
relocations?: Array<Relocation>;
};
Sources: modules/svelte-effect-runtime-language-server/src/patch-language-server/types.ts:65-88
Conclusion
The Language Server Internals of Svelte Effect Runtime represent a sophisticated patching layer over the standard Svelte developer experience. By leveraging runtime interception and virtual document projection, the server enables advanced effectful syntax while maintaining compatibility with the broader Svelte and TypeScript ecosystem. This architecture ensures that developers receive accurate diagnostics and IDE features for yield* based code without requiring upstream changes to official Svelte tooling.