How yioneko/vtsls works
Project type and purpose
• vtsls is an open-source Language Server Protocol (LSP) wrapper around the TypeScript language features extension shipped with VSCode.
• Its goal is to provide nearly identical TS editing features (completion, diagnostics, code actions, etc.) via a standalone language server while applying minimal patches to stay in sync with upstream updates effortlessly.
File structure
Top-level:
• .github/ & CI/CD files – workflows for testing, publishing, schema updates.
• package.json, pnpm-workspace.yaml – monorepo managed by pnpm.
• packages/ – three sub-packages:
– server/ – the CLI and LSP server bootstrap (bin/vtsls.js, build scripts, src/).
– service/ – core LSP implementation that loads the VSCode extension, applies patches, and delegates LSP requests. Contains:
• patches/ – diff files to alter upstream extension behavior.
• scripts/ – build helpers & patch runner.
• src/service/ – logic mapping LSP methods (completion, inlay hints, code actions) to extension APIs.
• src/shims/ – wrappers over VSCode extension APIs to surface them in a language-server context.
• src/share/ & src/utils/ – shared converters and utilities.
• tests/ – integration tests against a sample workspace.
– vscode-fuzzy/ – standalone fuzzy matching utility reused by the service for server-side completion filtering.
README for additional insights
• Describes LSP features supported, patching strategy, configuration schema, CLI usage (vtsls --stdio), and integration points (e.g., typescript.selectTypeScriptVersion).
• Emphasizes minimal patches and near-upstream parity.
Main components & their interactions
a. Components
1. LSP Client (editor or other LSP-aware tool)
2. CLI Entrypoint (vtsls --stdio)
3. Language Server Core (packages/server)
4. Service Layer (packages/service)
• Patch Manager (applies patches/*.patch to the bundled VSCode TS extension)
• Shim Layer (src/shims/*)
• Service Handlers (src/service/*.ts)
• Shared Converters & Utilities (src/share, src/utils)
5. Bundled VSCode TypeScript Extension (external code module)
6. TypeScript Server Process (tsserver) – either bundled or workspace version
7. Fuzzy Filtering Library (vscode-fuzzy)
8. Configuration Schema (configuration.schema.json)
b. Relationships & Data Flow
• The LSP Client ↔️ JSON-RPC over stdio ↔️ CLI Entrypoint
• CLI loads Language Server Core → initializes Service Layer
• Service Layer loads & patches the VSCode extension code, then spins up or communicates with tsserver
• Service Handlers convert incoming LSP requests → calls into shim APIs → underlying extension/tsserver → results back through shim → LSP response
• Completion requests optionally pass candidates through vscode-fuzzy for server-side filtering
• Configuration settings (from client) are validated against configuration.schema.json and drive behavior (e.g. patch toggles, memory limits)
c. Architectural patterns & principles
• Monorepo with clear package boundaries (server vs service vs utility)
• Adapter/Shim pattern to expose VSCode extension APIs in an LSP context
• Patch/Extension point model to apply minimal diffs to upstream code
• Separation of concerns: CLI vs server runtime vs core service logic vs utilities
d. Key technologies
• Node.js for runtime
• pnpm workspace (monorepo)
• TypeScript for all packages
• Vitest for tests
• JSON-RPC & vscode-language-server libraries
• Upstream VSCode TypeScript extension as a submodule
Elements
– Blue for vtsls-owned code (server, service, shims)
– Green for utilities (vscode-fuzzy, utils)
– Grey for external modules (VSCode extension, tsserver, editors)
– Rectangles for runtime components
Final advice
• Be very detailed: break the Service Layer into Patch Manager, Shim, Handler, and Utility subsystems.
• Configuration flow: client settings → schema validator → runtime toggles.