{"id":15707,"library":"monaco-languageclient","title":"Monaco Language Client","description":"Monaco Language Client (monaco-languageclient), currently at stable version 10.7.0, is a TypeScript-first library designed to bridge the gap between the Monaco Editor and Language Server Protocol (LSP) compatible language servers. It provides the necessary plumbing to integrate rich language features like syntax highlighting, auto-completion, diagnostics, and more into web-based Monaco instances. The library maintains an active release cadence, with major versions like v10 introducing significant architectural shifts. A key differentiator is its deep integration and reliance on `@codingame/monaco-vscode-api`, which allows it to offer a comprehensive toolbox for building VSCode Web-compatible applications, far beyond a simple LSP client. It separates core functionalities into distinct sub-exports, such as `vscodeApiWrapper` for VSCode API handling, `lcwrapper` for managing language clients, and `editorApp` for single editor control, enabling developers to construct sophisticated editor environments. This modular approach, coupled with its focus on modern ESM, makes it a robust solution for complex web-based IDEs.","status":"active","version":"10.7.0","language":"javascript","source_language":"en","source_url":"https://github.com/TypeFox/monaco-languageclient","tags":["javascript","typescript"],"install":[{"cmd":"npm install monaco-languageclient","lang":"bash","label":"npm"},{"cmd":"yarn add monaco-languageclient","lang":"bash","label":"yarn"},{"cmd":"pnpm add monaco-languageclient","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required as the underlying editor for which language server capabilities are provided. This is a peer dependency.","package":"monaco-editor","optional":false},{"reason":"Core dependency for providing VSCode API compatibility and services within the Monaco editor. This is a peer dependency.","package":"@codingame/monaco-vscode-api","optional":false}],"imports":[{"note":"Since v10, components are exposed via domain-specific sub-exports. Importing from the root package will not work.","wrong":"import { EditorApp } from 'monaco-languageclient';","symbol":"EditorApp","correct":"import { EditorApp, type EditorAppConfig } from 'monaco-languageclient/editorApp';"},{"note":"This library is primarily ESM-focused, especially since v10. Using CommonJS `require` for sub-exports is generally incorrect.","wrong":"const MonacoVscodeApiWrapper = require('monaco-languageclient/vscodeApiWrapper');","symbol":"MonacoVscodeApiWrapper","correct":"import { MonacoVscodeApiWrapper, type MonacoVscodeApiConfig } from 'monaco-languageclient/vscodeApiWrapper';"},{"note":"Always use named imports for `LanguageClientWrapper` and its associated types, as it is not a default export.","wrong":"import LanguageClientWrapper from 'monaco-languageclient/lcwrapper';","symbol":"LanguageClientWrapper","correct":"import { LanguageClientWrapper, type LanguageClientConfig } from 'monaco-languageclient/lcwrapper';"}],"quickstart":{"code":"import * as vscode from 'vscode'; // Assumes @codingame/monaco-vscode-api is configured to provide this\nimport { EditorApp, type EditorAppConfig } from 'monaco-languageclient/editorApp';\nimport { configureDefaultWorkerFactory } from 'monaco-languageclient/workerFactory';\nimport { MonacoVscodeApiWrapper, type MonacoVscodeApiConfig } from 'monaco-languageclient/vscodeApiWrapper';\nimport { LanguageClientWrapper, type LanguageClientConfig } from 'monaco-languageclient/lcwrapper';\n\n// Configure the default worker factory for Monaco, essential for web workers\nconfigureDefaultWorkerFactory();\n\nasync function createEditorAndLanguageClient() {\n    const languageId = 'mylang';\n    const code = `// Welcome to the Monaco Language Client example!\\nconst hello: string = \"world\";\\n`;\n    // Using vscode.Uri assumes @codingame/monaco-vscode-api is providing the VSCode API.\n    const codeUri = vscode.Uri.parse('/workspace/hello.mylang');\n\n    // 1. Monaco VSCode API configuration and initialization\n    const vscodeApiConfig: MonacoVscodeApiConfig = {\n        $type: 'extended',\n        viewsConfig: {\n            $type: 'EditorService' // Essential for managing editor views\n        }\n    };\n    const wrapper = new MonacoVscodeApiWrapper();\n    // This must be called ONLY ONCE in the application's lifecycle\n    await wrapper.initAndStart(vscodeApiConfig);\n    console.log('Monaco VSCode API initialized.');\n\n    // 2. Editor Application configuration and setup\n    const editorAppConfig: EditorAppConfig = {\n        $type: 'codeEditor',\n        languageId: languageId,\n        code: code,\n        uri: codeUri,\n        theme: 'vs-dark',\n        height: '80vh',\n        width: '100%'\n    };\n    const editorApp = new EditorApp(editorAppConfig);\n    editorApp.init();\n    editorApp.addEditorLoadedEventListener(() => {\n        console.log('Monaco editor loaded!');\n    });\n    // Mount the editor to a DOM element (e.g., <div id=\"monaco-editor-root\"></div>)\n    // Note: In a real app, you'd call editorApp.start(document.getElementById('monaco-editor-root')!); here.\n\n    // 3. Language Client configuration for a WebSocket connection\n    const languageClientConfig: LanguageClientConfig = {\n        languageId: languageId,\n        name: 'My Language Server',\n        serverPath: 'ws://localhost:3000/samplelsp', // Replace with your actual language server WebSocket URL\n        clientOptions: {\n            documentSelector: [{ language: languageId }]\n        },\n        // Define how to establish and manage the WebSocket connection\n        connectionProvider: {\n            get: async () => {\n                const webSocket = new WebSocket('ws://localhost:3000/samplelsp');\n                // You might need more robust error handling and lifecycle management for WebSocket\n                return {\n                    reader: (event: MessageEvent) => JSON.parse(event.data),\n                    writer: (message: any) => webSocket.send(JSON.stringify(message)),\n                    dispose: () => webSocket.close(),\n                    onError: (cb) => webSocket.addEventListener('error', cb),\n                    onClose: (cb) => webSocket.addEventListener('close', cb)\n                };\n            }\n        }\n    };\n    const languageClient = new LanguageClientWrapper();\n    await languageClient.start(languageClientConfig);\n\n    console.log('Monaco Editor and Language Client are configured and starting...');\n}\n\n// Execute the setup function\n// In a browser environment, call this after the DOM is ready.\ncreateEditorAndLanguageClient().catch(console.error);\n","lang":"typescript","description":"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+."},"warnings":[{"fix":"Review the migration guide for v10. Update import statements to use specific sub-exports (e.g., `import { EditorApp } from 'monaco-languageclient/editorApp';`). Refactor application initialization to use `MonacoVscodeApiWrapper`, `EditorApp`, and `LanguageClientWrapper` separately.","message":"Version 10 of `monaco-languageclient` introduced significant architectural changes. The previous `monaco-editor-wrapper` module was dropped, and its functionality, along with core `monaco-languageclient` features, was reorganized into domain-specific sub-exports like `/editorApp`, `/vscodeApiWrapper`, and `/lcwrapper`. This necessitates updating all import paths and refactoring application setup code.","severity":"breaking","affected_versions":">=10.0.0"},{"fix":"Ensure `MonacoVscodeApiWrapper.initAndStart()` is executed only once, typically during the initial application startup phase (e.g., when your main application component mounts or on initial page load).","message":"The `MonacoVscodeApiWrapper.initAndStart()` method, which initializes the underlying `@codingame/monaco-vscode-api` services, must be called exactly once per application's lifecycle. Repeated calls can lead to errors or undefined behavior as it attempts to re-initialize global VSCode services.","severity":"gotcha","affected_versions":">=2.0.0"},{"fix":"Upgrade your Node.js environment to version 20.10.0 or higher and your npm client to version 10.2.3 or higher. Consider using a Node Version Manager (nvm, Volta) to manage different Node.js versions.","message":"As of version 10.x, `monaco-languageclient` enforces strict engine requirements: Node.js >=20.10.0 and npm >=10.2.3. Using older versions of Node.js or npm may lead to installation failures or unexpected runtime issues.","severity":"breaking","affected_versions":">=10.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Update import paths to use the correct sub-exports, for example, change `import { EditorApp } from 'monaco-languageclient';` to `import { EditorApp } from 'monaco-languageclient/editorApp';`.","cause":"Attempting to import components directly from the root `monaco-languageclient` package instead of its specific sub-exports, a breaking change introduced in v10.","error":"Error: Cannot find module 'monaco-languageclient' or its corresponding type declarations."},{"fix":"Refactor your application to ensure that `MonacoVscodeApiWrapper.initAndStart()` is called only once during the initial setup, before any other Monaco or language client operations.","cause":"The `MonacoVscodeApiWrapper.initAndStart()` method was invoked more than once within the application's lifecycle, which is not permitted.","error":"MonacoVscodeApiWrapper: The VS Code API has already been initialized."},{"fix":"Convert 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.","cause":"Trying to use `require()` (CommonJS syntax) to import `monaco-languageclient` components, which are primarily distributed as ES Modules (ESM) since recent major versions.","error":"ERR_REQUIRE_ESM: Must use import to load ES Module: .../node_modules/monaco-languageclient/lcwrapper/index.js"}],"ecosystem":"npm"}