monaco-languageclient

The monaco-languageclient library enables the integration of the Monaco Editor with language clients and language servers using the Language Server Protocol (LSP). It allows you to build web-based editors with full LSP features such as code completion and diagnostics.

Key use cases include:

• Integrating language server features into web applications using Monaco Editor.
• Building custom language support for specific programming languages in a web environment.
• Using WebSocket or Web Worker connections to communicate with remote language servers.

This repository contains several specialized npm packages for integrating Monaco Editor with language servers and React:

• monaco-languageclient: Connects the Monaco editor with language servers.
• vscode-ws-jsonrpc: Implements communication between a JSON-RPC client and server over WebSockets.
• @typefox/monaco-editor-react: Provides React components to make the editor and language client available within a React application.
• monaco-languageclient-examples: Contains examples that can be used externally.

To integrate a Langium-based DSL into a web application using monaco-languageclient, you need to focus on two main areas: connecting the language server to the editor and setting up the logic for dispatching and handling notifications and requests.

These guides assume you have a working Langium language and have completed the basic monaco-languageclient getting started steps.

For a complete, runnable implementation, refer to the MiniLogo example in the repository, which demonstrates a Langium DSL running in the browser with Monaco using the langium-minilogo package.

When extending communication between a Langium language server and a Monaco client, choose between these two patterns based on the operation's nature:

When setting up the full editor environment, you must initialize the components in a specific order to ensure services and language support are available when the editor starts:

1. MonacoVscodeApiWrapper.start(): Initializes the VS Code API layer, registers extensions, and sets up editor workers/themes. Must be first.
2. LanguageClientWrapper.start(): Connects to the language server worker. The API layer must be ready for the client to register itself.
3. EditorApp.start(): Creates the Monaco editor instance and loads content. This must be last as it relies on the API and language services being ready.

If you start the EditorApp before these steps, the editor will function but will lack language support and VS Code-related features.

The Monaco Language Client uses a layered configuration approach consisting of three distinct layers:

1. VSCode API Configuration: Controls editor services and behavior (e.g., themes, keybindings).
2. Language Client Configuration: Manages the connection to language servers (e.g., WebSocket URLs, document selectors).
3. Editor App Configuration: Defines code resources and the overall editor setup.

Regardless of whether you use classic or extended mode, you must configure and start the MonacoVscodeApiWrapper first.

Running a Langium-based language server (LS) in the browser involves three main components:

1. A browser entry point: A file (e.g., main-browser.ts) that starts the language server using browser-compatible communication and file system abstractions.
2. A bundled worker: The entry point bundled into a standalone Web Worker (typically as an ES module).
3. A Monaco client: A monaco-languageclient application that loads the worker and establishes a connection.

This pattern allows you to run the full language intelligence (autocompletion, diagnostics, etc.) entirely on the client side without a Node.js backend.

When designing communication between a client and a Langium language server, choose between Notifications and Requests based on the following trade-offs:

Note that both patterns can be used in either direction (client-to-server or server-to-client).

The library functions as a bridge between the editor and the language server through the following lifecycle:

1. Receive events from the Monaco Editor (e.g., typing, cursor movement).
2. Translate events into LSP messages.
3. Send messages to a language server via WebSockets or Web Workers.
4. Receive responses from the language server.
5. Supply the Monaco Editor with language features (completions, diagnostics, etc.).

The Monaco Language Client provides two integration modes. Extended Mode is the recommended starting point for most use cases.

Extended Mode

Uses @codingame/monaco-vscode-api to provide VSCode-like services.

• Best for: Applications wanting a full VSCode-like experience, including advanced editor features, extension-like capabilities, and VSCode Web extensions.
• Key dependency: @codingame/monaco-vscode-api.

Classic Mode

Uses a standalone Monaco Editor with language client features added on top.

• Best for: Lightweight applications that need core LSP features (completions, diagnostics) but want a smaller bundle size and simpler integration without the VSCode API.
• Trade-off: Lacks the advanced services and features provided by the extended mode.