Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
LanguageClient
✓ import { LanguageClient } from 'vscode-languageclient/node';
✗ const { LanguageClient } = require('vscode-languageclient');
For Node.js environments (like typical VS Code extensions), use the `/node` subpath. For browser-based clients (e.g., web extensions), use `/browser`.
LanguageClientOptions
✓ import { LanguageClientOptions } from 'vscode-languageclient/node';
This interface defines the client's behavior and configuration, such as document selectors and synchronization options.
ServerOptions, TransportKind
✓ import { ServerOptions, TransportKind } from 'vscode-languageclient/node';
These types are crucial for configuring how the client connects to and launches the language server, including the communication transport method (e.g., stdio, ipc, tcp).
This quickstart demonstrates how to set up and activate a `LanguageClient` in a VS Code extension, configuring it to connect to a Node.js-based language server via standard I/O (stdio) and handle its lifecycle.
import * as path from 'path';
import { ExtensionContext, workspace } from 'vscode';
import { LanguageClient, LanguageClientOptions, ServerOptions, TransportKind } from 'vscode-languageclient/node';
let client: LanguageClient;
export function activate(context: ExtensionContext) {
// The server is implemented in Node.js
// Path to the server module (your actual language server's main file)
const serverModule = context.asAbsolutePath(path.join('server', 'out', 'server.js'));
// Debug options for the server
// --inspect=6009: runs the server in Node's Inspector mode so VS Code can attach to it
const debugOptions = { execArgv: ['--nolazy', '--inspect=6009'] };
// Server options: either run or debug mode
const serverOptions: ServerOptions = {
run: { module: serverModule, transport: TransportKind.stdio },
debug: { module: serverModule, transport: TransportKind.stdio, options: debugOptions }
};
// Options to control the language client
const clientOptions: LanguageClientOptions = {
// Register the server for documents matching a specific language ID or scheme
documentSelector: [{ scheme: 'file', language: 'plaintext' }],
synchronize: {
// Notify the server about file changes to '.clientrc' files in the workspace
fileEvents: workspace.createFileSystemWatcher('**/.clientrc')
},
outputChannelName: 'My Language Client',
traceOutputChannel: workspace.window.createOutputChannel('My Language Client Trace')
};
// Create the language client and start it. This will also launch the server.
client = new LanguageClient(
'myLanguageServer',
'My Language Server',
serverOptions,
clientOptions
);
// Start the client. This returns a disposable which will stop the client
// when the extension is deactivated.
client.start();
// Add the client to the context's subscriptions so it is stopped on deactivate
context.subscriptions.push(client);
}
export function deactivate(): Thenable<void> | undefined {
if (!client) {
return undefined;
}
return client.stop();
}
Debug
Known issues
breakingVersion 9.0.0 and above of `vscode-languageclient` explicitly require VS Code engine version `^1.82.0` or higher. Using older VS Code versions may lead to activation failures or unexpected behavior.fixEnsure your `package.json` specifies `"engines": { "vscode": "^1.82.0" }` or a compatible version. Update your VS Code installation if necessary. affects: >=9.0.0
gotchaIn `vscode-languageclient` versions prior to `10.0.0-next.20`, the client could prematurely request `textDocument/diagnostics` before sending the `textDocument/didOpen` notification to the server. This could lead to server errors if the server expects the document to be open first.fixUpgrade `vscode-languageclient` to `10.0.0-next.20` or a later stable version to ensure correct request ordering.
affects: <10.0.0-next.20
gotchaSpecific `next` versions leading up to `10.0.0-next.11` of `vscode-languageclient` were found to have an 'output channel leak' when stopping a `LanguageClient`, potentially consuming resources over time with frequent client restarts.fixUpdate `vscode-languageclient` to `10.0.0-next.11` or a later stable release to benefit from the fix for the output channel leak.
affects: <10.0.0-next.11
gotchaThe `jsonrpc` package (a core dependency) introduced `NoInfer` for better typing in `10.0.0-next.11`. While an improvement, this might subtly change type inference in custom request/notification handlers if your code previously relied on broader type compatibility.fixReview any custom LSP handlers or generic utility functions that interact with `vscode-languageserver-protocol` types for potential type inference changes and adjust type annotations as needed.
affects: >=10.0.0-next.11
Errors
Common errors & fixes
Language client 'myLanguageServer' failed to launch.
The language server process specified in `serverOptions` failed to start, crashed immediately, or exited prematurely. This often points to an issue within the server's main script or its dependencies.
fixVerify the `serverModule` path in `serverOptions` is correct and points to an executable script. Enable debugging for the server (e.g., using `--inspect` in `debugOptions`) and attach a debugger to diagnose server startup issues. Check the language client's output channel in VS Code for any logged server errors or messages.
Cannot find module 'vscode'
This error occurs when client-side extension code, which relies on the `vscode` API, is executed outside of a running VS Code instance (e.g., directly in Node.js or a web browser). The `vscode` module is a host-provided API, not an npm installable package for runtime.
fixEnsure your extension is correctly packaged and run within VS Code. When developing, use the 'Run Extension' debug configuration. If building for a specific environment, ensure `vscode` is correctly declared as a `peerDependency` in your extension's `package.json` and handled by your build process.
Client requests textDocument/diagnostics before textDocument/didOpen
This was a known bug in specific `vscode-languageclient` versions (prior to `10.0.0-next.20`) where the client would send `textDocument/diagnostics` requests to the server before the `textDocument/didOpen` notification, leading to potential server errors or incorrect state where the server hadn't processed the document yet.
fixUpdate `vscode-languageclient` to `10.0.0-next.20` or a later stable version (e.g., `10.0.0` once released) to resolve the incorrect request order and ensure proper document lifecycle management.
Audit
Dependencies
vscoderequiredRequired peer dependency for access to the VS Code API and extension activation lifecycle.
vscode-languageserver-protocolrequiredCore dependency providing the Language Server Protocol's types and definitions, essential for client-server communication.
vscode-languageserver-typesrequiredProvides basic LSP types commonly used in both client and server implementations.