0
# VSCode Language Client
1

2
VSCode Language Client is a TypeScript library that enables VSCode extensions to easily integrate with Language Server Protocol (LSP) servers. It provides a robust client implementation handling communication between VSCode extensions and language servers, supporting features like diagnostics, code completion, hover information, go-to-definition, and other language intelligence capabilities.
3

4
## Package Information
5

6
- **Package Name**: vscode-languageclient
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install vscode-languageclient`
10
- **VSCode Engine**: ^1.82.0
11

12
## Core Imports
13

14
```typescript
15
import { LanguageClient, LanguageClientOptions, ServerOptions } from "vscode-languageclient/node";
16
```
17

18
For browser environments:
19

20
```typescript
21
import { LanguageClient, LanguageClientOptions } from "vscode-languageclient/browser";
22
```
23

24
All protocol types:
25

26
```typescript
27
import { 
28
  InitializeParams, 
29
  ServerCapabilities, 
30
  CompletionRequest,
31
  HoverRequest,
32
  // ... other protocol types
33
} from "vscode-languageserver-protocol";
34
```
35

36
## Basic Usage
37

38
```typescript
39
import { LanguageClient, LanguageClientOptions, ServerOptions, TransportKind } from "vscode-languageclient/node";
40

41
// Define server options
42
const serverOptions: ServerOptions = {
43
  run: { command: 'my-language-server', transport: TransportKind.stdio },
44
  debug: { command: 'my-language-server', args: ['--debug'], transport: TransportKind.stdio }
45
};
46

47
// Define client options
48
const clientOptions: LanguageClientOptions = {
49
  documentSelector: [{ scheme: 'file', language: 'mylang' }],
50
  synchronize: {
51
    fileEvents: workspace.createFileSystemWatcher('**/.mylangrc')
52
  }
53
};
54

55
// Create and start the client
56
const client = new LanguageClient(
57
  'mylang-client',
58
  'My Language Client',
59
  serverOptions,
60
  clientOptions
61
);
62

63
await client.start();
64
```
65

66
## Architecture
67

68
VSCode Language Client is built around several key components:
69

70
- **Client Classes**: Core client implementations for Node.js and browser environments
71
- **Transport Layer**: Multiple transport options (stdio, IPC, pipes, sockets) for server communication  
72
- **Feature System**: Modular architecture supporting all LSP capabilities through middleware
73
- **Protocol Integration**: Complete integration with Language Server Protocol specification
74
- **Configuration System**: Flexible options for customizing client behavior and server interaction
75

76
## Capabilities
77

78
### Core Client API
79

80
Main client classes and lifecycle management for establishing and maintaining language server connections.
81

82
```typescript { .api }
83
abstract class BaseLanguageClient {
84
  start(): Promise<void>;
85
  stop(timeout?: number): Promise<void>;
86
  dispose(timeout?: number): Promise<void>;
87
  sendRequest<R, PR, E, RO>(type: ProtocolRequestType<PR, R, E, RO>, params: PR, token?: CancellationToken): Promise<R>;
88
  sendRequest<R, E>(type: RequestType0<R, E>, token?: CancellationToken): Promise<R>;
89
  sendRequest<P, R, E>(type: RequestType<P, R, E>, params: P, token?: CancellationToken): Promise<R>;
90
  sendNotification<RO>(type: ProtocolNotificationType<RO, any>, params?: RO): Promise<void>;
91
  sendNotification<P>(type: NotificationType<P>, params?: P): Promise<void>;
92
  sendNotification(type: NotificationType0): Promise<void>;
93
  onRequest<R, PR, E, RO>(type: ProtocolRequestType<PR, R, E, RO>, handler: RequestHandler<PR, R, E>): Disposable;
94
  onRequest<R, E>(type: RequestType0<R, E>, handler: RequestHandler0<R, E>): Disposable;
95
  onRequest<P, R, E>(type: RequestType<P, R, E>, handler: RequestHandler<P, R, E>): Disposable;
96
  onNotification<RO>(type: ProtocolNotificationType<RO, any>, handler: NotificationHandler<RO>): Disposable;
97
  onNotification<P>(type: NotificationType<P>, handler: NotificationHandler<P>): Disposable;
98
  onNotification(type: NotificationType0, handler: NotificationHandler0): Disposable;
99
}
100

101
class LanguageClient extends BaseLanguageClient {
102
  constructor(name: string, serverOptions: ServerOptions, clientOptions: LanguageClientOptions, forceDebug?: boolean);
103
  constructor(id: string, name: string, serverOptions: ServerOptions, clientOptions: LanguageClientOptions, forceDebug?: boolean);
104
}
105
```
106

107
[Core Client](./core-client.md)
108

109
### Configuration and Options
110

111
Configuration interfaces and types for customizing client behavior, server options, and middleware setup.
112

113
```typescript { .api }
114
interface LanguageClientOptions {
115
  documentSelector?: DocumentSelector | string[];
116
  diagnosticCollectionName?: string;
117
  outputChannel?: OutputChannel;
118
  revealOutputChannelOn?: RevealOutputChannelOn;
119
  initializationOptions?: any | (() => any);
120
  middleware?: Middleware;
121
  errorHandler?: ErrorHandler;
122
  synchronize?: SynchronizeOptions;
123
  connectionOptions?: ConnectionOptions;
124
}
125

126
type ServerOptions = Executable | { run: Executable; debug: Executable } | NodeModule | (() => Promise<ChildProcess | StreamInfo | MessageTransports>);
127

128
enum RevealOutputChannelOn {
129
  Debug = 0,
130
  Info = 1, 
131
  Warn = 2,
132
  Error = 3,
133
  Never = 4
134
}
135
```
136

137
[Configuration](./configuration.md) 
138

139
### Language Features
140

141
Middleware interfaces for all Language Server Protocol features including completion, hover, diagnostics, and code actions.
142

143
```typescript { .api }
144
interface Middleware {
145
  completion?: CompletionMiddleware;
146
  hover?: HoverMiddleware;
147
  signatureHelp?: SignatureHelpMiddleware;
148
  definition?: DefinitionMiddleware;
149
  references?: ReferencesMiddleware;
150
  documentHighlight?: DocumentHighlightMiddleware;
151
  documentSymbol?: DocumentSymbolMiddleware;
152
  codeAction?: CodeActionMiddleware;
153
  codeLens?: CodeLensMiddleware;
154
  formatting?: FormattingMiddleware;
155
  rename?: RenameMiddleware;
156
  // ... other feature middleware
157
}
158

159
interface CompletionMiddleware {
160
  provideCompletionItem?: ProvideCompletionItemsSignature;
161
  resolveCompletionItem?: ResolveCompletionItemSignature;
162
}
163
```
164

165
[Language Features](./language-features.md)
166

167
### Transport and Communication
168

169
Transport configuration and message handling for different communication channels between client and server.
170

171
```typescript { .api }
172
enum TransportKind {
173
  stdio,
174
  ipc,
175
  pipe,
176
  socket
177
}
178

179
interface Executable {
180
  command: string;
181
  args?: string[];
182
  transport?: Transport;
183
  options?: ExecutableOptions;
184
}
185

186
interface MessageTransports {
187
  reader: MessageReader;
188
  writer: MessageWriter;
189
  detached?: boolean;
190
}
191
```
192

193
[Transport](./transport.md)
194

195
### Feature System
196

197
Base interfaces and classes for implementing static and dynamic language server features.
198

199
```typescript { .api }
200
interface StaticFeature {
201
  fillInitializeParams?(params: InitializeParams): void;
202
  fillClientCapabilities(capabilities: ClientCapabilities): void;
203
  initialize(capabilities: ServerCapabilities, documentSelector: DocumentSelector | undefined): void;
204
  getState(): FeatureState;
205
  clear(): void;
206
}
207

208
interface DynamicFeature<RO> extends StaticFeature {
209
  registrationType: RegistrationType<RO>;
210
  register(data: RegistrationData<RO>): void;
211
  unregister(id: string): void;
212
}
213
```
214

215
[Feature System](./feature-system.md)
216

217
### Utilities and Helpers
218

219
Utility classes and functions for error handling, configuration monitoring, and type conversion.
220

221
```typescript { .api }
222
class SettingMonitor {
223
  constructor(client: LanguageClient, setting: string);
224
  start(): Disposable;
225
}
226

227
class LSPCancellationError extends Error {
228
  readonly data: any;
229
  constructor(data: any);
230
}
231

232
class Code2ProtocolConverter {
233
  // Methods for converting VS Code types to LSP protocol types
234
}
235

236
class Protocol2CodeConverter {
237
  // Methods for converting LSP protocol types to VS Code types
238
}
239
```
240

241
[Utilities](./utilities.md)
242

243
## Types
244

245
### Core Types
246

247
```typescript { .api }
248
enum State {
249
  Stopped = 1,
250
  Starting = 3,
251
  Running = 2
252
}
253

254
enum ErrorAction {
255
  Continue = 1,
256
  Shutdown = 2
257
}
258

259
enum CloseAction {
260
  DoNotRestart = 1,
261
  Restart = 2
262
}
263

264
interface StateChangeEvent {
265
  oldState: State;
266
  newState: State;
267
}
268

269
interface ConnectionOptions {
270
  cancellationStrategy?: CancellationStrategy;
271
  messageStrategy?: MessageStrategy;
272
  maxRestartCount?: number;
273
}
274
```
275

276
### Error Handling Types
277

278
```typescript { .api }
279
interface ErrorHandler {
280
  error(error: Error, message: Message | undefined, count: number | undefined): ErrorAction;
281
  closed(): CloseAction;
282
}
283

284
interface InitializationFailedHandler {
285
  (error: ResponseError<InitializeError> | Error | any): boolean;
286
}
287
```