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.
EditorApp
✓ import { EditorApp, type EditorAppConfig } from 'monaco-languageclient/editorApp';
✗ import { EditorApp } from 'monaco-languageclient';
Since v10, components are exposed via domain-specific sub-exports. Importing from the root package will not work.
MonacoVscodeApiWrapper
✓ import { MonacoVscodeApiWrapper, type MonacoVscodeApiConfig } from 'monaco-languageclient/vscodeApiWrapper';
✗ const MonacoVscodeApiWrapper = require('monaco-languageclient/vscodeApiWrapper');
This library is primarily ESM-focused, especially since v10. Using CommonJS `require` for sub-exports is generally incorrect.
LanguageClientWrapper
✓ import { LanguageClientWrapper, type LanguageClientConfig } from 'monaco-languageclient/lcwrapper';
✗ import LanguageClientWrapper from 'monaco-languageclient/lcwrapper';
Always use named imports for `LanguageClientWrapper` and its associated types, as it is not a default export.
This quickstart demonstrates the core setup for initializing the VSCode API, configuring a Monaco editor application, and connecting it to a language server via WebSocket using `monaco-languageclient`'s modular components. It illustrates the structured approach required by v10+.
import * as vscode from 'vscode'; // Assumes @codingame/monaco-vscode-api is configured to provide this
import { EditorApp, type EditorAppConfig } from 'monaco-languageclient/editorApp';
import { configureDefaultWorkerFactory } from 'monaco-languageclient/workerFactory';
import { MonacoVscodeApiWrapper, type MonacoVscodeApiConfig } from 'monaco-languageclient/vscodeApiWrapper';
import { LanguageClientWrapper, type LanguageClientConfig } from 'monaco-languageclient/lcwrapper';
// Configure the default worker factory for Monaco, essential for web workers
configureDefaultWorkerFactory();
async function createEditorAndLanguageClient() {
const languageId = 'mylang';
const code = `// Welcome to the Monaco Language Client example!\nconst hello: string = "world";\n`;
// Using vscode.Uri assumes @codingame/monaco-vscode-api is providing the VSCode API.
const codeUri = vscode.Uri.parse('/workspace/hello.mylang');
// 1. Monaco VSCode API configuration and initialization
const vscodeApiConfig: MonacoVscodeApiConfig = {
$type: 'extended',
viewsConfig: {
$type: 'EditorService' // Essential for managing editor views
}
};
const wrapper = new MonacoVscodeApiWrapper();
// This must be called ONLY ONCE in the application's lifecycle
await wrapper.initAndStart(vscodeApiConfig);
console.log('Monaco VSCode API initialized.');
// 2. Editor Application configuration and setup
const editorAppConfig: EditorAppConfig = {
$type: 'codeEditor',
languageId: languageId,
code: code,
uri: codeUri,
theme: 'vs-dark',
height: '80vh',
width: '100%'
};
const editorApp = new EditorApp(editorAppConfig);
editorApp.init();
editorApp.addEditorLoadedEventListener(() => {
console.log('Monaco editor loaded!');
});
// Mount the editor to a DOM element (e.g., <div id="monaco-editor-root"></div>)
// Note: In a real app, you'd call editorApp.start(document.getElementById('monaco-editor-root')!); here.
// 3. Language Client configuration for a WebSocket connection
const languageClientConfig: LanguageClientConfig = {
languageId: languageId,
name: 'My Language Server',
serverPath: 'ws://localhost:3000/samplelsp', // Replace with your actual language server WebSocket URL
clientOptions: {
documentSelector: [{ language: languageId }]
},
// Define how to establish and manage the WebSocket connection
connectionProvider: {
get: async () => {
const webSocket = new WebSocket('ws://localhost:3000/samplelsp');
// You might need more robust error handling and lifecycle management for WebSocket
return {
reader: (event: MessageEvent) => JSON.parse(event.data),
writer: (message: any) => webSocket.send(JSON.stringify(message)),
dispose: () => webSocket.close(),
onError: (cb) => webSocket.addEventListener('error', cb),
onClose: (cb) => webSocket.addEventListener('close', cb)
};
}
}
};
const languageClient = new LanguageClientWrapper();
await languageClient.start(languageClientConfig);
console.log('Monaco Editor and Language Client are configured and starting...');
}
// Execute the setup function
// In a browser environment, call this after the DOM is ready.
createEditorAndLanguageClient().catch(console.error);
Errors
Common errors & fixes
Error: Cannot find module 'monaco-languageclient' or its corresponding type declarations.
Attempting to import components directly from the root `monaco-languageclient` package instead of its specific sub-exports, a breaking change introduced in v10.
fixUpdate import paths to use the correct sub-exports, for example, change `import { EditorApp } from 'monaco-languageclient';` to `import { EditorApp } from 'monaco-languageclient/editorApp';`. MonacoVscodeApiWrapper: The VS Code API has already been initialized.
The `MonacoVscodeApiWrapper.initAndStart()` method was invoked more than once within the application's lifecycle, which is not permitted.
fixRefactor your application to ensure that `MonacoVscodeApiWrapper.initAndStart()` is called only once during the initial setup, before any other Monaco or language client operations.
ERR_REQUIRE_ESM: Must use import to load ES Module: .../node_modules/monaco-languageclient/lcwrapper/index.js
Trying to use `require()` (CommonJS syntax) to import `monaco-languageclient` components, which are primarily distributed as ES Modules (ESM) since recent major versions.
fixConvert your project or relevant files to use ES Module syntax (e.g., add `"type": "module"` to your `package.json` and use `import` statements) or ensure your build tooling correctly handles ESM for your target environment.
Audit
Dependencies
monaco-editorrequiredRequired as the underlying editor for which language server capabilities are provided. This is a peer dependency.
@codingame/monaco-vscode-apirequiredCore dependency for providing VSCode API compatibility and services within the Monaco editor. This is a peer dependency.