{"id":12392,"library":"vscode-languageserver","title":"VS Code Language Server","description":"The `vscode-languageserver` package provides a Node.js-based implementation of the Language Server Protocol (LSP), allowing developers to build language servers that offer rich language-specific features (e.g., autocomplete, diagnostics, go-to-definition, refactoring) to various text editors and IDEs, primarily VS Code. It abstracts the complexities of the LSP specification and JSON-RPC communication, enabling a focus on core language logic. The current stable version is `9.0.1`, with `10.0.0` actively in `next` development, signaling upcoming significant updates and LSP specification alignments. This project is a core component of the official VS Code ecosystem, characterized by its robust, well-maintained, and protocol-compliant tooling, making it a de facto standard for Node.js-based LSP servers. The release cadence includes frequent `next` versions for client, server, protocol, and jsonrpc packages, reflecting continuous integration and adaptation to evolving LSP standards.","status":"active","version":"9.0.1","language":"javascript","source_language":"en","source_url":"https://github.com/Microsoft/vscode-languageserver-node","tags":["javascript","typescript"],"install":[{"cmd":"npm install vscode-languageserver","lang":"bash","label":"npm"},{"cmd":"yarn add vscode-languageserver","lang":"bash","label":"yarn"},{"cmd":"pnpm add vscode-languageserver","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Defines the Language Server Protocol types and messages for communication between client and server.","package":"vscode-languageserver-protocol","optional":false},{"reason":"Provides core data structures and types used across the Language Server Protocol, such as `TextDocumentIdentifier`, `Range`, and `Position`.","package":"vscode-languageserver-types","optional":false},{"reason":"Handles the underlying JSON-RPC communication mechanism, enabling message passing over standard I/O, IPC, or network sockets.","package":"vscode-jsonrpc","optional":false},{"reason":"Provides a robust implementation for managing text documents, including capabilities for incremental updates, which is crucial for efficient server performance.","package":"vscode-languageserver-textdocument","optional":false}],"imports":[{"note":"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.","wrong":"const createConnection = require('vscode-languageserver').createConnection;","symbol":"createConnection","correct":"import { createConnection, ProposedFeatures } from 'vscode-languageserver/node';"},{"note":"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.","wrong":"import { TextDocuments } from 'vscode-languageserver';\nconst documents = new TextDocuments();","symbol":"TextDocuments","correct":"import { TextDocuments } from 'vscode-languageserver';\nimport { TextDocument } from 'vscode-languageserver-textdocument';\nconst documents = new TextDocuments(TextDocument);"},{"note":"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`.","wrong":"import { InitializeParams } from 'vscode-languageserver';","symbol":"InitializeParams","correct":"import type { InitializeParams } from 'vscode-languageserver';"}],"quickstart":{"code":"import {\n  createConnection,\n  TextDocuments,\n  ProposedFeatures,\n  InitializeParams,\n  InitializeResult,\n  TextDocumentSyncKind,\n} from 'vscode-languageserver/node';\nimport { TextDocument } from 'vscode-languageserver-textdocument';\n\n// Create a connection for the server. The connection uses Node's IPC as a transport.\nconst connection = createConnection(ProposedFeatures.all);\n\n// Create a simple text document manager. The text document manager\n// supports full document sync only and tracks open, change, and close events.\nconst documents: TextDocuments<TextDocument> = new TextDocuments(TextDocument);\n\nconnection.onInitialize((params: InitializeParams) => {\n  const capabilities = params.capabilities;\n\n  const result: InitializeResult = {\n    capabilities: {\n      textDocumentSync: TextDocumentSyncKind.Full,\n      // Tell the client that the server supports code completion\n      completionProvider: {\n        resolveProvider: true, // We need to resolve additional information for a completion item\n        triggerCharacters: ['.']\n      },\n      hoverProvider: true,\n    },\n  };\n  return result;\n});\n\nconnection.onInitialized(() => {\n  connection.console.log('Language server initialized!');\n});\n\n// The content of a text document has changed. This event is emitted\n// when the text document first opened or when its content has changed.\ndocuments.onDidChangeContent(change => {\n  connection.console.log(`Document changed: ${change.document.uri}`);\n  // In a real server, you would perform diagnostics here\n  // connection.sendDiagnostics({ uri: change.document.uri, diagnostics: [] });\n});\n\nconnection.onCompletion(\n  (_textDocumentPosition, _token) => {\n    // This is a very basic completion provider. In a real server,\n    // you would analyze the document and provide context-aware suggestions.\n    return [\n      { label: 'console', kind: 18 }, // Method\n      { label: 'log', kind: 6 }, // Function\n      { label: 'warn', kind: 6 },\n      { label: 'error', kind: 6 }\n    ];\n  }\n);\n\n// This handler resolves additional information for the selected completion item.\nconnection.onCompletionResolve((item) => {\n  if (item.label === 'log') {\n    item.detail = 'Logs a message to the console.';\n    item.documentation = 'The `console.log()` method outputs a message to the web console.';\n  }\n  return item;\n});\n\n// Make the text document manager listen on the connection\n// for open, change and close text document events\ndocuments.listen(connection);\n\n// Listen on the connection\nconnection.listen();","lang":"typescript","description":"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."},"warnings":[{"fix":"Consult 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`).","message":"The 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).","severity":"breaking","affected_versions":">=10.0.0-next"},{"fix":"Ensure `TextDocument` is imported from `vscode-languageserver-textdocument` and passed to the `TextDocuments` constructor: `import { TextDocument } from 'vscode-languageserver-textdocument'; const documents = new TextDocuments(TextDocument);`","message":"When 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.","severity":"gotcha","affected_versions":">=6.0.0"},{"fix":"Always use the `/node` subpath for Node.js-specific imports: `import { createConnection, ProposedFeatures } from 'vscode-languageserver/node';`","message":"It'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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"For 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.","message":"Running `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.","severity":"gotcha","affected_versions":"All versions when used in browser environments"},{"fix":"Ensure your `connection.onInitialize` handler returns an `InitializeResult` object with all desired `ServerCapabilities` explicitly declared. For example: `return { capabilities: { textDocumentSync: TextDocumentSyncKind.Full, completionProvider: { resolveProvider: true } } };`","message":"An 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"For optimal performance, configure `textDocumentSync` to `TextDocumentSyncKind.Incremental` and implement logic to handle partial document updates. The `vscode-languageserver-textdocument` package supports incremental updates.","message":"Older 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.","severity":"deprecated","affected_versions":"<6.0.0 (and still functional but less efficient in later versions)"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure `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';`.","cause":"Incorrect import path or missing dependency installation for the Language Server package.","error":"Error: Cannot find module 'vscode-languageserver/node'"},{"fix":"Use the `TextDocuments` instance to listen for document events: `documents.listen(connection); documents.onDidChangeContent(...)`.","cause":"Attempting to directly register document event handlers on the `connection` object. Document management is now abstracted by `TextDocuments`.","error":"Property 'onDidOpenTextDocument' does not exist on type 'Connection'."},{"fix":"Ensure the `connection.onInitialize` callback returns a valid `InitializeResult` object, typically like: `return { capabilities: { textDocumentSync: TextDocumentSyncKind.Full } };`.","cause":"The `onInitialize` handler must return an `InitializeResult` object describing the server's capabilities, not `null` or `undefined`.","error":"Type 'null' is not assignable to type 'InitializeResult'."},{"fix":"Check 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.","cause":"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.","error":"There was an error activating the remote language server (or similar client-side activation errors)."}],"ecosystem":"npm"}