0
# Configuration
1

2
Configuration interfaces and types for customizing client behavior, server options, and middleware setup.
3

4
## Capabilities
5

6
### LanguageClientOptions
7

8
Main configuration interface for customizing language client behavior.
9

10
```typescript { .api }
11
/**
12
 * Configuration options for the language client
13
 */
14
interface LanguageClientOptions {
15
  /** 
16
   * Document selector defining which documents this client should handle.
17
   * Can be a DocumentSelector or array of language identifiers.
18
   */
19
  documentSelector?: DocumentSelector | string[];
20
  
21
  /** Name for the diagnostic collection created by this client */
22
  diagnosticCollectionName?: string;
23
  
24
  /** Custom output channel for client messages */
25
  outputChannel?: OutputChannel;
26
  
27
  /** Name for the output channel if not providing a custom one */
28
  outputChannelName?: string;
29
  
30
  /** Custom output channel for trace messages */
31
  traceOutputChannel?: OutputChannel;
32
  
33
  /** When to automatically reveal the output channel */
34
  revealOutputChannelOn?: RevealOutputChannelOn;
35
  
36
  /** Encoding for stdio communication (Node.js only) */
37
  stdioEncoding?: string;
38
  
39
  /** 
40
   * Options passed to the language server during initialization.
41
   * Can be a value or function returning a value.
42
   */
43
  initializationOptions?: any | (() => any);
44
  
45
  /** Handler called when initialization fails */
46
  initializationFailedHandler?: InitializationFailedHandler;
47
  
48
  /** Whether to show progress during initialization */
49
  progressOnInitialization?: boolean;
50
  
51
  /** Custom error handler for connection errors */
52
  errorHandler?: ErrorHandler;
53
  
54
  /** Middleware for customizing feature behavior */
55
  middleware?: Middleware;
56
  
57
  /** URI converters for path translation */
58
  uriConverters?: {
59
    code2Protocol: c2p.URIConverter;
60
    protocol2Code: p2c.URIConverter;
61
  };
62
  
63
  /** Override the workspace folder */
64
  workspaceFolder?: WorkspaceFolder;
65
  
66
  /** Connection-level configuration options */
67
  connectionOptions?: ConnectionOptions;
68
  
69
  /** Markdown rendering configuration */
70
  markdown?: {
71
    isTrusted?: boolean | { readonly enabledCommands: readonly string[] };
72
    supportHtml?: boolean;
73
  };
74
  
75
  /** File synchronization options */
76
  synchronize?: SynchronizeOptions;
77
  
78
  /** Diagnostic pull mode configuration */
79
  diagnosticPullOptions?: DiagnosticPullOptions;
80
  
81
  /** Notebook document synchronization options */
82
  notebookDocumentOptions?: NotebookDocumentOptions;
83
}
84
```
85

86
**Usage Examples:**
87

88
Basic client configuration:
89

90
```typescript
91
import { LanguageClientOptions } from "vscode-languageclient/node";
92

93
const clientOptions: LanguageClientOptions = {
94
  documentSelector: [{ scheme: 'file', language: 'typescript' }],
95
  synchronize: {
96
    fileEvents: workspace.createFileSystemWatcher('**/*.ts')
97
  }
98
};
99
```
100

101
Advanced configuration with middleware:
102

103
```typescript
104
const clientOptions: LanguageClientOptions = {
105
  documentSelector: [{ scheme: 'file', language: 'mylang' }],
106
  outputChannelName: 'My Language Server',
107
  revealOutputChannelOn: RevealOutputChannelOn.Error,
108
  initializationOptions: {
109
    customSetting: true,
110
    maxDiagnostics: 100
111
  },
112
  middleware: {
113
    completion: {
114
      provideCompletionItem: (document, position, context, token, next) => {
115
        // Custom completion logic
116
        return next(document, position, context, token);
117
      }
118
    }
119
  },
120
  errorHandler: {
121
    error: (error, message, count) => {
122
      console.log(`Connection error: ${error.message}`);
123
      return ErrorAction.Continue;
124
    },
125
    closed: () => {
126
      console.log('Connection closed');
127
      return CloseAction.Restart;
128
    }
129
  }
130
};
131
```
132

133
### ServerOptions (Node.js)
134

135
Configuration for language server processes in Node.js environments.
136

137
```typescript { .api }
138
/**
139
 * Server configuration options for Node.js clients
140
 */
141
type ServerOptions = 
142
  | Executable 
143
  | { run: Executable; debug: Executable }
144
  | { run: NodeModule; debug: NodeModule }
145
  | NodeModule 
146
  | (() => Promise<ChildProcess | StreamInfo | MessageTransports | ChildProcessInfo>);
147

148
/**
149
 * Configuration for executable language servers
150
 */
151
interface Executable {
152
  /** Command to execute */
153
  command: string;
154
  /** Command line arguments */
155
  args?: string[];
156
  /** Transport mechanism for communication */
157
  transport?: Transport;
158
  /** Additional execution options */
159
  options?: ExecutableOptions;
160
}
161

162
/**
163
 * Configuration for Node.js module language servers
164
 */
165
interface NodeModule {
166
  /** Path to the Node.js module */
167
  module: string;
168
  /** Arguments passed to the module */
169
  args?: string[];
170
  /** Transport mechanism for communication */
171
  transport?: Transport;
172
  /** Node.js runtime path (defaults to 'node') */
173
  runtime?: string;
174
  /** Fork options for child process */
175
  options?: ForkOptions;
176
}
177

178
/**
179
 * Stream-based server information
180
 */
181
interface StreamInfo {
182
  /** Writable stream for sending messages to server */
183
  writer: NodeJS.WritableStream;
184
  /** Readable stream for receiving messages from server */
185
  reader: NodeJS.ReadableStream;
186
  /** Whether the streams are detached from client lifecycle */
187
  detached?: boolean;
188
}
189

190
/**
191
 * Child process information with additional metadata
192
 */
193
interface ChildProcessInfo {
194
  /** The spawned child process */
195
  process: ChildProcess;
196
  /** Whether the process is detached */
197
  detached?: boolean;
198
}
199
```
200

201
**Usage Examples:**
202

203
Executable server configuration:
204

205
```typescript
206
const serverOptions: ServerOptions = {
207
  run: { 
208
    command: 'my-language-server',
209
    args: ['--stdio'],
210
    transport: TransportKind.stdio
211
  },
212
  debug: { 
213
    command: 'my-language-server',
214
    args: ['--stdio', '--debug'],
215
    transport: TransportKind.stdio
216
  }
217
};
218
```
219

220
Node module server:
221

222
```typescript
223
const serverOptions: ServerOptions = {
224
  module: './path/to/server.js',
225
  transport: TransportKind.ipc,
226
  options: {
227
    env: { ...process.env, DEBUG: 'true' }
228
  }
229
};
230
```
231

232
Dynamic server creation:
233

234
```typescript
235
const serverOptions: ServerOptions = async () => {
236
  const serverProcess = spawn('my-server', ['--pipe']);
237
  return {
238
    reader: serverProcess.stdout,
239
    writer: serverProcess.stdin
240
  };
241
};
242
```
243

244
### Output Channel Configuration
245

246
```typescript { .api }
247
/**
248
 * When to reveal the output channel
249
 */
250
enum RevealOutputChannelOn {
251
  /** Reveal on debug messages */
252
  Debug = 0,
253
  /** Reveal on info messages */
254
  Info = 1,
255
  /** Reveal on warning messages */
256
  Warn = 2,
257
  /** Reveal on error messages */
258
  Error = 3,
259
  /** Never automatically reveal */
260
  Never = 4
261
}
262
```
263

264
### Connection Configuration
265

266
```typescript { .api }
267
/**
268
 * Connection-level configuration options
269
 */
270
interface ConnectionOptions {
271
  /** Strategy for handling request cancellation */
272
  cancellationStrategy?: CancellationStrategy;
273
  /** Strategy for handling message transmission */
274
  messageStrategy?: MessageStrategy;
275
  /** Maximum number of restart attempts */
276
  maxRestartCount?: number;
277
}
278

279
/**
280
 * Strategy for handling request cancellation
281
 */
282
interface CancellationStrategy {
283
  /** Create a cancellation token for a request */
284
  sender: {
285
    sendCancellation(conn: MessageConnection, id: string | number): void;
286
    cleanup(id: string | number): void;
287
  };
288
  /** Handle cancellation from the other side */
289
  receiver: {
290
    createCancellationTokenSource(id: string | number): CancellationTokenSource;
291
    cleanup(id: string | number): void;
292
  };
293
}
294

295
/**
296
 * Strategy for handling message transmission
297
 */
298
interface MessageStrategy {
299
  /** Handle a request message */
300
  handleMessage(message: Message, next: (message: Message) => void): void;
301
}
302
```
303

304
### File Synchronization
305

306
```typescript { .api }
307
/**
308
 * File synchronization configuration
309
 */
310
interface SynchronizeOptions {
311
  /** 
312
   * Configuration section(s) to synchronize.
313
   * String or array of configuration section names.
314
   */
315
  configurationSection?: string | string[];
316
  
317
  /** File system watchers to register with the server */
318
  fileEvents?: FileSystemWatcher | FileSystemWatcher[];
319
}
320
```
321

322
### Error Handling
323

324
```typescript { .api }
325
/**
326
 * Handler for connection errors
327
 */
328
interface ErrorHandler {
329
  /**
330
   * Handle a connection error
331
   * @param error - The error that occurred
332
   * @param message - The message being processed when error occurred
333
   * @param count - Number of errors encountered
334
   * @returns Action to take in response to the error
335
   */
336
  error(error: Error, message: Message | undefined, count: number | undefined): ErrorAction;
337
  
338
  /**
339
   * Handle connection closed
340
   * @returns Action to take when connection is closed
341
   */
342
  closed(): CloseAction;
343
}
344

345
/**
346
 * Handler for initialization failures
347
 */
348
interface InitializationFailedHandler {
349
  /**
350
   * Handle initialization failure
351
   * @param error - The initialization error
352
   * @returns Whether to retry initialization
353
   */
354
  (error: ResponseError<InitializeError> | Error | any): boolean;
355
}
356

357
/**
358
 * Actions to take when an error occurs
359
 */
360
enum ErrorAction {
361
  /** Continue processing despite the error */
362
  Continue = 1,
363
  /** Shutdown the client */
364
  Shutdown = 2
365
}
366

367
/**
368
 * Actions to take when connection is closed
369
 */
370
enum CloseAction {
371
  /** Do not restart the connection */
372
  DoNotRestart = 1,
373
  /** Restart the connection */
374
  Restart = 2
375
}
376
```
377

378
### Diagnostics Configuration
379

380
```typescript { .api }
381
/**
382
 * Configuration for diagnostic pull mode
383
 */
384
interface DiagnosticPullOptions {
385
  /** When to trigger diagnostic requests */
386
  onChange?: boolean;
387
  /** When to trigger diagnostic requests on save */
388
  onSave?: boolean;
389
}
390

391
/**
392
 * Diagnostic pull modes
393
 */
394
enum DiagnosticPullMode {
395
  /** Pull diagnostics on document change */
396
  onType,
397
  /** Pull diagnostics on document save */
398
  onSave
399
}
400
```