lsp-refactor

lspeasy

A TypeScript SDK for building Language Server Protocol clients and servers that run anywhere JavaScript runs — Node, browsers, web workers, or VS Code extensions — with a capability-aware, strongly-typed API.

⚠️ Pre-1.0 software — APIs are subject to change between minor versions. Pin to exact versions in production. See the CHANGELOG for breaking changes between releases.

📚 Documentation: https://pradeepmouli.github.io/lspeasy/

Overview

The Language Server Protocol standardizes how editors and IDEs talk to language tooling — hover, completion, diagnostics, symbol navigation, and dozens of other features all flow over a single JSON-RPC connection. Implementing a server or client against LSP directly is deceptively involved: you need JSON-RPC framing, message validation, cancellation tokens, progress reporting, capability negotiation, the full lifecycle handshake, and correct handling of roughly a hundred request and notification types.

lspeasy is a set of small, focused TypeScript packages that wrap all of that in a modern, ESM-first API. Handlers are registered against a typed, capability-aware namespace — server.textDocument.onHover(...) — so the editor-facing surface mirrors the spec and advertised capabilities are enforced at both compile time and runtime. Transports are swappable: run the same server over stdio for a classic editor plugin, over a web worker for a browser playground, over WebSockets for a remote tooling backend, or over TCP for diagnostics.

Compared to vscode-languageserver (which is tightly coupled to Node and the VS Code extension model), lspeasy is runtime-agnostic, tree-shakeable, browser-friendly, and exposes a middleware pipeline for logging, tracing, and request rewriting without monkey-patching the dispatcher.

Features

• Capability-aware handler registration — server.textDocument.onHover(...) is only callable after registerCapabilities({ hoverProvider: true }); mismatches are caught at both compile time and at the dispatcher.
• Full JSON-RPC 2.0 core — schemas, framing, request/notification/response types, and typed error codes, all validated with Zod.
• Swappable transports — StdioTransport, TcpTransport, IpcTransport, WebSocketTransport, DedicatedWorkerTransport, SharedWorkerTransport; write your own against the Transport interface.
• Runs anywhere — Node.js-specific transports live under @lspeasy/core/node; the root export is browser-safe so the same code ships to a VS Code extension and a web playground.
• Typed client API — client.textDocument.hover(...), client.workspace.symbol(...), and the full request surface with request/response types pulled from the LSP spec.
• Composable middleware — composeMiddleware(...) plus createScopedMiddleware({ methods, direction }) for logging, tracing, metrics, or request mutation without touching the core dispatcher.
• Lifecycle + progress + cancellation — initialize/initialized/shutdown/exit are handled for you, with built-in partial-result and work-done progress senders and CancellationToken support.
• Zod-validated messages — every inbound message is parsed against a schema, so malformed peers surface as typed errors instead of runtime crashes.
• Tree-shakeable, ESM-only — pay for what you import; no CommonJS compatibility shims dragging extra code into browser bundles.

Install

# Build a server
pnpm add @lspeasy/server @lspeasy/core

# Build a client
pnpm add @lspeasy/client @lspeasy/core

Requires Node.js ≥ 20. For WebSocket server mode or Node < 22.4, also install ws (optional peer): pnpm add ws.

Quick Start

A minimal LSP server over stdio that responds to textDocument/hover:

import { LSPServer } from '@lspeasy/server';
import { StdioTransport } from '@lspeasy/core/node';

const server = new LSPServer({ name: 'hello-lsp', version: '0.1.0' });

server.registerCapabilities({ hoverProvider: true });

server.textDocument.onHover(async (params) => ({
  contents: {
    kind: 'markdown',
    value: `**Hovered** line ${params.position.line}, character ${params.position.character}`
  }
}));

await server.listen(new StdioTransport());