This repository hosts multiple packages under one roof:
- monaco-languageclient to connect Monaco editor with language servers.
- vscode-ws-jsonrpc which implements communication between a jsonrpc client and server over WebSocket.
- @typefox/monaco-editor-react makes editor and language client available within a React component.
- monaco-languageclient-examples provides the examples used in this repository and by the verification projects.
The examples not requiring a backend are now available via GitHub Pages.
- Monaco Language Client, VSCode WebSocket Json RPC, Monaco Editor React and examples
- Official Documentation
- Changelogs, current versions and compatibility table
- Getting started
- Usage
- Examples Overview
- Main Examples
- JSON Language client and language server example (Location)
- Python Language client and pyright language server example (Location)
- Groovy Language client and language server example (Location)
- Java Language client and language server example (Location)
- Cpp / Clangd (Location)
- Application Playground (Location)
- Langium grammar DSL (Location)
- Langium MiniLogo DSL (Location)
- Statemachine DSL (created with Langium) (Location)
- Browser example (Location)
- Purely monaco-editor related examples
- Server processes
- Verification Examples & Usage
- VSCode integration
- Main Examples
- Featured projects
- Troubleshooting
- Licenses
Since monaco-languageclient version 10 we started to build an official documentation. This will be continuously extended.
We maintain a migration guide for major version upgrades.
CHANGELOGs for each project are available from the linked location:
- CHANGELOG for
monaco-languageclientis found here - CHANGELOG for
vscode-ws-jsonrpcis found here - CHANGELOG for
@typefox/monaco-editor-reactis found here - CHANGELOG for
monaco-languageclient-examplesis found here
Important Project changes and notes about the project's history are found here.
These are the current versions of packages from this repository and their alignment with @codingame/monaco-vscode-api monaco-editor and vscode:
- monaco-languageclient:
11.0.0(release date: unreleased) - @typefox/monaco-editor-react:
8.0.0(release date: unreleased) - monaco-languageclient-examples: private package
- Aligned with:
- @codingame/monaco-vscode-[editor]-api:
37.1.0 - vscode:
1.138.0 - monaco-editor:
0.56.0
- @codingame/monaco-vscode-[editor]-api:
- vscode-ws-jsonrpc:
4.0.0(release date: unreleased)
Find the full compatibility table with all previous versions.
We recommend mise-en-place to set up correct versions of required tools like node and npm (described here). If you have mise installed, use the optional instruction below.
On your local machine you can prepare your dev environment as follows. At first it is advised to build everything. Locally, from a terminal do:
# clone the git repository
git clone https://github.com/TypeFox/monaco-languageclient.git
cd monaco-languageclient
# optional: if you have mise installed
mise upgrade
# install npm dependencies
npm i
# Cleans-up, compiles and builds everything
npm run build
# downloads additional files needed for some examples
npm run init:examplesStart the Vite dev server. It serves all client code at localhost. You can go to the index.html and navigate to all client examples from there. You can edit the client example code directly (TypeScript) and Vite ensures it automatically made available:
npm run dev
# OR: this clears the cache and has debug output
npm run dev:debugAs this is a npm workspace, the main package.json contains script entries applicable to the whole workspace like watch, build and lint, but it also contains shortcuts for launching scripts from the child packages like npm run build:examples.
If you want to change the libraries and see this reflected directly, run the watch command that compiles all TypeScript files from the libraries and the examples:
npm run watchPlease look at the respective section in the packages:
- Usage for
monaco-languageclientis found here - Usage for
vscode-ws-jsonrpcis found here - Usage for
@typefox/monaco-editor-reactis found here
The examples demonstrate multiple things:
- How
monaco-languageclientand@typefox/monaco-editor-reactcan provide an editor connected to a language server that runs either in a browser worker or in an external process via WebSocket andvscode-ws-jsonrpc. - How different language servers can be integrated in a common way, so they can communicate via WebSocket with the front-end running in the browser.
JSON Language client and language server example (Location)
The json-server runs an external Node.js Express app where web sockets are used to enable communication between the language server process and the client web application (see JSON Language Server). The json-client using extended mode as editor app which connects to the language server and therefore requires the node server app to be run in parallel. The json-client using classic mode as editor app which connects to the language server and therefore requires the node server app to be run in parallel.
Python Language client and pyright language server example (Location)
The python-server runs an external Node.js Express app where web sockets are used to enable communication between the language server process and the client web application (see Pyright Language Server). The python-client contains the editor app which connects to the language server and therefore requires the node server app to be run in parallel. It is also possible to use a @typefox/monaco-editor-react app to connect to the server. Both versions now feature a debugger, see here.
Groovy Language client and language server example (Location)
The groovy-server runs an external Java app where web sockets are used to enable communication between the language server process and the client web application (Groovy Language Server). The groovy-client contains the editor app which connects to the language server and therefore requires the node server app to be run in parallel.
Java Language client and language server example (Location)
The java-server runs an external Java app where web sockets are used to enable communication between the language server process and the client web application (Java Language Server). The java-client contains the editor app which connects to the language server and therefore requires the node server app to be run in parallel.
Langium examples communicate via vscode-languageserver-protocol/browser instead of the WebSocket setup used in the server-backed examples above.
Cpp / Clangd (Location)
It contains both the language client and the language server (web worker). The clangd language server is compiled to wasm so it can be executed in the browser. Heads up: This is a prototype and still evolving.
Application Playground (Location)
This example uses the view service provider from @codingame/monaco-vscode-editor-api to build an application that utilizes more vscode features. Alternatively, it is possible to use a react version of the app Heads up: This is a prototype and still evolving.
Langium grammar DSL (Location)
It contains both the language client and the language server (web worker).
Langium MiniLogo DSL (Location)
It contains both the language client and a worker-based MiniLogo language server from langium-minilogo.
Statemachine DSL (created with Langium) (Location)
It contains both the language client and the language server (web worker). It is also possible to use a @typefox/monaco-editor-react app to connect to the server.
Browser example (Location)
This demonstrates how an editor app can be combined with a language service written in JavaScript. This example can now be considered legacy as the web worker option eases client side language server implementation and separation, but it still shows a valid way to achieve the desired outcome.
See Typescript Language support.
For all json client related examples you need to ensure the json-server example is running:
# start the express server with the language server running in the same process.
npm run start:example:server:jsonFor the python-client example you need to ensure the python-server example is running:
# start the express server with the language server running as external node process.
npm run start:example:server:pythonIf you want to use the debugger in the python-client example you need to the debugger is running. You require docker-compose to run it. From the project root run docker-compose -f ./packages/examples/resources/debugger/docker-compose.yml up -d. First start up will take longer as the container is downloaded from GitHub's container registry. Use docker-compose -f ./packages/examples/resources/debugger/docker-compose.yml down to stop it.
For the groovy-client example you need to ensure the groovy-server example is running. You require docker-compose which does not require any manual setup (OpenJDK / Gradle). From the project root run docker-compose -f ./packages/examples/resources/groovy/docker-compose.yml up -d. First start up will take longer as the container is downloaded from GitHub's container registry. Use docker-compose -f ./packages/examples/resources/groovy/docker-compose.yml down to stop it.
For the java-client example you need to ensure the java-server example is running. You require docker-compose which does not require any manual setup (OpenJDK / Eclipse JDT LS). From the project root run docker-compose -f ./packages/examples/resources/eclipse.jdt.ls/docker-compose.yml up -d. First start up will take longer as the container is downloaded from GitHub's container registry. Use docker-compose -f ./packages/examples/resources/eclipse.jdt.ls/docker-compose.yml down to stop it.
None of the verification examples is part of the npm workspace. Some bring a substantial amount of npm dependencies that would pollute the main node_modules dependencies and therefore these examples need to be built and started independently.
-
webpack verification example demonstrates how bundling can be achieved with webpack. You find the configuration here: webpack.config.js. Please do:
cd verify/webpack && npm run verify. It serves the client here: http://localhost:8082. -
Next.js verification example: demonstrates how to use
@typefox/monaco-editor-reactwith Next.js, Please do:cd verify/next && npm run verify. It serves the client here: http://localhost:8083. -
Angular verification example: If you want to test it, please do:
cd verify/angular && npm run verify. It serves the client here: http://localhost:8084. Important:monaco-languageclientcurrently does not support the Angular build as it breaks the development and production build. We therefore use@analogjs/vite-plugin-angularwhich relies on Vite.
You can as well run vscode tasks to start and debug the server in different modes and the client.
For troubleshooting, please also see the Troubleshooting Guide.