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.
createConnection
✓ import { createConnection, ProposedFeatures } from 'vscode-languageserver/node';
✗ const createConnection = require('vscode-languageserver').createConnection;
The `/node` subpath is crucial for Node.js environments to ensure proper module resolution and access to Node.js-specific IPC features. `ProposedFeatures.all` is commonly used to enable all proposed LSP features for a connection.
TextDocuments
✓ import { TextDocuments } from 'vscode-languageserver';
import { TextDocument } from 'vscode-languageserver-textdocument';
const documents = new TextDocuments(TextDocument);
✗ import { TextDocuments } from 'vscode-languageserver';
const documents = new TextDocuments();
Since `vscode-languageserver@6.0.0`, the `TextDocuments` class requires an instance of `TextDocument` (from `vscode-languageserver-textdocument`) as a factory to create and manage text documents, deprecating the previous internal implementation.
InitializeParams
✓ import type { InitializeParams } from 'vscode-languageserver';
✗ import { InitializeParams } from 'vscode-languageserver';
Always use `import type` for importing types when possible. This ensures that the import is purely for type-checking and doesn't generate unnecessary runtime code, which is especially relevant for large type definitions like LSP protocol messages. These types are often re-exported from `vscode-languageserver-protocol`.
This quickstart sets up a basic Language Server that listens for 'initialize' and 'didChangeContent' events, and provides simple completion items. It demonstrates connection creation, document management, and basic server capabilities declaration.
import {
createConnection,
TextDocuments,
ProposedFeatures,
InitializeParams,
InitializeResult,
TextDocumentSyncKind,
} from 'vscode-languageserver/node';
import { TextDocument } from 'vscode-languageserver-textdocument';
// Create a connection for the server. The connection uses Node's IPC as a transport.
const connection = createConnection(ProposedFeatures.all);
// Create a simple text document manager. The text document manager
// supports full document sync only and tracks open, change, and close events.
const documents: TextDocuments<TextDocument> = new TextDocuments(TextDocument);
connection.onInitialize((params: InitializeParams) => {
const capabilities = params.capabilities;
const result: InitializeResult = {
capabilities: {
textDocumentSync: TextDocumentSyncKind.Full,
// Tell the client that the server supports code completion
completionProvider: {
resolveProvider: true, // We need to resolve additional information for a completion item
triggerCharacters: ['.']
},
hoverProvider: true,
},
};
return result;
});
connection.onInitialized(() => {
connection.console.log('Language server initialized!');
});
// The content of a text document has changed. This event is emitted
// when the text document first opened or when its content has changed.
documents.onDidChangeContent(change => {
connection.console.log(`Document changed: ${change.document.uri}`);
// In a real server, you would perform diagnostics here
// connection.sendDiagnostics({ uri: change.document.uri, diagnostics: [] });
});
connection.onCompletion(
(_textDocumentPosition, _token) => {
// This is a very basic completion provider. In a real server,
// you would analyze the document and provide context-aware suggestions.
return [
{ label: 'console', kind: 18 }, // Method
{ label: 'log', kind: 6 }, // Function
{ label: 'warn', kind: 6 },
{ label: 'error', kind: 6 }
];
}
);
// This handler resolves additional information for the selected completion item.
connection.onCompletionResolve((item) => {
if (item.label === 'log') {
item.detail = 'Logs a message to the console.';
item.documentation = 'The `console.log()` method outputs a message to the web console.';
}
return item;
});
// Make the text document manager listen on the connection
// for open, change and close text document events
documents.listen(connection);
// Listen on the connection
connection.listen();
Debug
Known issues
breakingThe upcoming `10.0.0` major release (currently in `next` state) is expected to introduce significant breaking changes. These changes will likely affect API usage, especially for `Connection` and `TextDocuments`, and will align with new LSP specifications and internal architectural improvements. Users upgrading from `9.x` should review the release notes carefully. Key areas of change include how modules use `exports` in `package.json`, compiler upgrades, and updated Node.js environment requirements (e.g., Node.js 22.13.14 and `es2022` target).fixConsult the `vscode-languageserver-node` GitHub repository and release notes for detailed migration guides when upgrading to `10.x`. Adjust `tsconfig.json` to reflect `moduleResolution` and `module` settings compatible with the new `exports` property in package.json files (e.g., using `node16`).
affects: >=10.0.0-next
gotchaWhen initializing `TextDocuments`, the constructor requires a `TextDocument` factory from `vscode-languageserver-textdocument` (e.g., `new TextDocuments(TextDocument)`). Older versions of the library allowed `new TextDocuments()`, but this was deprecated in `vscode-languageserver@6.0.0`. Failing to provide the factory will lead to runtime errors when documents are managed.fixEnsure `TextDocument` is imported from `vscode-languageserver-textdocument` and passed to the `TextDocuments` constructor: `import { TextDocument } from 'vscode-languageserver-textdocument'; const documents = new TextDocuments(TextDocument);` affects: >=6.0.0
gotchaIt's crucial to specify the `/node` subpath when importing `createConnection` and `ProposedFeatures` (e.g., `import { createConnection } from 'vscode-languageserver/node';`) for Node.js environments. Omitting this subpath can lead to module resolution issues or incorrect usage of browser-specific implementations, especially in modern module systems.fixAlways use the `/node` subpath for Node.js-specific imports: `import { createConnection, ProposedFeatures } from 'vscode-languageserver/node';` affects: All versions
gotchaRunning `vscode-languageserver` in a browser environment (e.g., a React app using Monaco Editor) can lead to errors related to Node.js built-in modules like `fs`. The core `vscode-languageserver` package is designed for Node.js, and directly importing it client-side without proper polyfills or shims for Node.js APIs will fail. Consider `vscode-languageserver-protocol` for browser-compatible type definitions or a browser-specific LSP implementation.fixFor browser-based LSP interactions, consider using `vscode-languageserver-protocol` for shared types without the Node.js runtime, or a dedicated browser-compatible language server client/server implementation. Do not directly import `vscode-languageserver` into frontend code.
affects: All versions when used in browser environments
gotchaAn LSP server must correctly declare its `capabilities` in the `InitializeResult` to inform the client which features it supports (e.g., `completionProvider`, `hoverProvider`, `textDocumentSync`). Incorrect or missing capability declarations will result in the client not activating those features, leading to a non-functional language experience.fixEnsure your `connection.onInitialize` handler returns an `InitializeResult` object with all desired `ServerCapabilities` explicitly declared. For example: `return { capabilities: { textDocumentSync: TextDocumentSyncKind.Full, completionProvider: { resolveProvider: true } } };` affects: All versions
deprecatedOlder methods for managing text document content, where the entire document content was sent on every change (full synchronization), are less efficient. While still supported, modern LSP implementations encourage incremental text document synchronization for better performance.fixFor optimal performance, configure `textDocumentSync` to `TextDocumentSyncKind.Incremental` and implement logic to handle partial document updates. The `vscode-languageserver-textdocument` package supports incremental updates.
affects: <6.0.0 (and still functional but less efficient in later versions)
Errors
Common errors & fixes
Error: Cannot find module 'vscode-languageserver/node'
Incorrect import path or missing dependency installation for the Language Server package.
fixEnsure `vscode-languageserver` is installed via `npm install vscode-languageserver` or `yarn add vscode-languageserver`. Verify the import path is `import { createConnection } from 'vscode-languageserver/node';`. Property 'onDidOpenTextDocument' does not exist on type 'Connection'.
Attempting to directly register document event handlers on the `connection` object. Document management is now abstracted by `TextDocuments`.
fixUse the `TextDocuments` instance to listen for document events: `documents.listen(connection); documents.onDidChangeContent(...)`.
Type 'null' is not assignable to type 'InitializeResult'.
The `onInitialize` handler must return an `InitializeResult` object describing the server's capabilities, not `null` or `undefined`.
fixEnsure the `connection.onInitialize` callback returns a valid `InitializeResult` object, typically like: `return { capabilities: { textDocumentSync: TextDocumentSyncKind.Full } };`. There was an error activating the remote language server (or similar client-side activation errors).
The client-side extension (e.g., `vscode-languageclient`) failed to establish or maintain a connection with the language server. This can be due to the server crashing on startup, incorrect IPC configuration, or permission issues.
fixCheck the language server's console output for errors. Ensure the `createConnection` call is correctly configured for IPC (e.g., `createConnection(ProposedFeatures.all)` for standard Node.js IPC). Verify there are no file access permission issues preventing the server from starting or writing logs. Implement robust `errorHandler` and `initializationFailedHandler` on the client side for better diagnostics.
Audit
Dependencies
vscode-languageserver-protocolrequiredDefines the Language Server Protocol types and messages for communication between client and server.
vscode-languageserver-typesrequiredProvides core data structures and types used across the Language Server Protocol, such as `TextDocumentIdentifier`, `Range`, and `Position`.
vscode-jsonrpcrequiredHandles the underlying JSON-RPC communication mechanism, enabling message passing over standard I/O, IPC, or network sockets.
vscode-languageserver-textdocumentrequiredProvides a robust implementation for managing text documents, including capabilities for incremental updates, which is crucial for efficient server performance.