{"id":15896,"library":"vscode-languageclient","title":"VSCode Language Client","description":"The `vscode-languageclient` package provides the foundational client-side implementation for integrating Language Servers into VS Code extensions. It fully adheres to the Language Server Protocol (LSP), abstracting away the complexities of inter-process communication, managing the language server's lifecycle (startup, shutdown, restart), and seamlessly mapping LSP messages to the corresponding VS Code API calls. This library is the official, actively maintained client by Microsoft, ensuring deep integration and compatibility with the editor's evolving features and API, making it the de-facto standard for building robust language extensions. The current stable version is 9.0.1, with active development evident through frequent `10.0.0-next.x` pre-releases, often aligning with major VS Code updates. Its release cadence is primarily driven by the needs of VS Code's extension ecosystem.","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-languageclient","lang":"bash","label":"npm"},{"cmd":"yarn add vscode-languageclient","lang":"bash","label":"yarn"},{"cmd":"pnpm add vscode-languageclient","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required peer dependency for access to the VS Code API and extension activation lifecycle.","package":"vscode","optional":false},{"reason":"Core dependency providing the Language Server Protocol's types and definitions, essential for client-server communication.","package":"vscode-languageserver-protocol","optional":false},{"reason":"Provides basic LSP types commonly used in both client and server implementations.","package":"vscode-languageserver-types","optional":false}],"imports":[{"note":"For Node.js environments (like typical VS Code extensions), use the `/node` subpath. For browser-based clients (e.g., web extensions), use `/browser`.","wrong":"const { LanguageClient } = require('vscode-languageclient');","symbol":"LanguageClient","correct":"import { LanguageClient } from 'vscode-languageclient/node';"},{"note":"This interface defines the client's behavior and configuration, such as document selectors and synchronization options.","symbol":"LanguageClientOptions","correct":"import { LanguageClientOptions } from 'vscode-languageclient/node';"},{"note":"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).","symbol":"ServerOptions, TransportKind","correct":"import { ServerOptions, TransportKind } from 'vscode-languageclient/node';"}],"quickstart":{"code":"import * as path from 'path';\nimport { ExtensionContext, workspace } from 'vscode';\nimport { LanguageClient, LanguageClientOptions, ServerOptions, TransportKind } from 'vscode-languageclient/node';\n\nlet client: LanguageClient;\n\nexport function activate(context: ExtensionContext) {\n  // The server is implemented in Node.js\n  // Path to the server module (your actual language server's main file)\n  const serverModule = context.asAbsolutePath(path.join('server', 'out', 'server.js'));\n\n  // Debug options for the server\n  // --inspect=6009: runs the server in Node's Inspector mode so VS Code can attach to it\n  const debugOptions = { execArgv: ['--nolazy', '--inspect=6009'] };\n\n  // Server options: either run or debug mode\n  const serverOptions: ServerOptions = {\n    run: { module: serverModule, transport: TransportKind.stdio },\n    debug: { module: serverModule, transport: TransportKind.stdio, options: debugOptions }\n  };\n\n  // Options to control the language client\n  const clientOptions: LanguageClientOptions = {\n    // Register the server for documents matching a specific language ID or scheme\n    documentSelector: [{ scheme: 'file', language: 'plaintext' }],\n    synchronize: {\n      // Notify the server about file changes to '.clientrc' files in the workspace\n      fileEvents: workspace.createFileSystemWatcher('**/.clientrc')\n    },\n    outputChannelName: 'My Language Client',\n    traceOutputChannel: workspace.window.createOutputChannel('My Language Client Trace')\n  };\n\n  // Create the language client and start it. This will also launch the server.\n  client = new LanguageClient(\n    'myLanguageServer',\n    'My Language Server',\n    serverOptions,\n    clientOptions\n  );\n\n  // Start the client. This returns a disposable which will stop the client\n  // when the extension is deactivated.\n  client.start();\n\n  // Add the client to the context's subscriptions so it is stopped on deactivate\n  context.subscriptions.push(client);\n}\n\nexport function deactivate(): Thenable<void> | undefined {\n  if (!client) {\n    return undefined;\n  }\n  return client.stop();\n}","lang":"typescript","description":"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."},"warnings":[{"fix":"Ensure your `package.json` specifies `\"engines\": { \"vscode\": \"^1.82.0\" }` or a compatible version. Update your VS Code installation if necessary.","message":"Version 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.","severity":"breaking","affected_versions":">=9.0.0"},{"fix":"Upgrade `vscode-languageclient` to `10.0.0-next.20` or a later stable version to ensure correct request ordering.","message":"In `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.","severity":"gotcha","affected_versions":"<10.0.0-next.20"},{"fix":"Update `vscode-languageclient` to `10.0.0-next.11` or a later stable release to benefit from the fix for the output channel leak.","message":"Specific `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.","severity":"gotcha","affected_versions":"<10.0.0-next.11"},{"fix":"Review 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.","message":"The `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.","severity":"gotcha","affected_versions":">=10.0.0-next.11"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Verify 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.","cause":"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.","error":"Language client 'myLanguageServer' failed to launch."},{"fix":"Ensure 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.","cause":"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.","error":"Cannot find module 'vscode'"},{"fix":"Update `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.","cause":"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.","error":"Client requests textDocument/diagnostics before textDocument/didOpen"}],"ecosystem":"npm"}