Repository files navigation

This repository now host multiple npm packages under one roof:

• monaco-languageclient to connectMonaco editor withlanguage servers.
• vscode-ws-jsonrpc which implements communication between a jsonrpc client and server over WebSocket.
• monaco-editor-wrapper for building monaco editor application driven by configuration
• monaco-editor-react puts a react cloack overmonaco-editor-wrapper
• monaco-languageclient-examples provides the examples which allows to use them externally.

The examples not requiring a backend are now availablevia GitHub Pages.

• Monaco Language Client, VSCode WebSocket Json RPC, Monaco-Editor-Wrapper, Monaco-Editor-React and examples
  • Changelogs, project history and compatibility
  • Getting started
    • Vite dev server
  • 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)
      • Statemachine DSL (created with Langium) (Location)
      • bare monaco-languageclient (Location)
      • Browser example (Location)
      • Purely monaco-editor related examples
      • Server processes
        • JSON Language Server
        • Pyright Language Server
        • Graalpy Debugger
        • Groovy Language Server
        • Java Language Server
    • Verification Examples & Usage
    • VSCode integration
  • Featured projects
  • Troubleshooting
    • General
    • @codingame/monaco-vscode-editor-api / monaco-editor usage
    • Dependency issues: monaco-editor / @codingame/monaco-vscode-api / @codingame/monaco-vscode-editor-api
    • Volta
    • Vite dev server troubleshooting
    • SSR frameworks
    • Serve all files required
    • Bad Polyfills
      • buffer
    • monaco-editor and react
    • webpack worker issues
  • Licenses

CHANGELOGs for each project are available from the linked location:

• CHANGELOG formonaco-languageclient is foundhere
• CHANGELOG forvscode-ws-jsonrpc is foundhere
• CHANGELOG formonaco-editor-wrapper is foundhere
• CHANGELOG for@typefox/monaco-editor-react is foundhere
• CHANGELOG formonaco-languageclient-examples is foundhere

Important Project changes and notes about the project's history are foundhere.

These are the current versions of packages from this repository and their alignment with@codingame/monaco-vscode-apimonaco-editor andvscode:

• monaco-languageclient:9.8.0 (release date: 2025-06-24)
• monaco-editor-wrapper:6.9.0 (release date: 2025-06-24)
• @typefox/monaco-editor-react:6.9.0 (release date: 2025-06-24)
• Aligned with:
  • @codingame/monaco-vscode-[editor]-api:18.1.0
  • vscode:1.101.1
  • monaco-editor:0.52.2
• vscode-ws-jsonrpc:3.4.0 (release date: 2024-12-18)

You find the full compatibility table with all previous versionshere.

This article describes the initial motivation for starting monaco-languageclient.

On your local machine you can prepare your dev environment as follows. At first it is advised to build everything. Or, use a fresh dev environment inGitpod by pressing thecode now badge above.Locally, from a terminal do:

git clone https://github.com/TypeFox/monaco-languageclient.gitcd monaco-languageclientnpm i# Cleans-up, compiles and builds everythingnpm run build

Start the Vite dev server. It serves all client code atlocalhost. You can go to theindex.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 outputnpm run dev:debug

As this is a npm workspace the mainpackage.json contains script entries applicable to the whole workspace likewatch,build andlint, but it also contains shortcuts for launching scripts from the childe packages likenpm run build:examples.

If you want to change the libries and see this reflected directly, then you need to run the watch command that compiles all TypeScript files form both libraries and the examples:

npm run watch

Please look at the respective section in the packages:

• Usage formonaco-languageclient is foundhere
• Usage forvscode-ws-jsonrpc is foundhere
• Usage formonaco-editor-wrapper is foundhere
• Usage for@typefox/monaco-editor-react is foundhere

The examples demonstrate mutliple things:

• Howmonaco-languageclient is use bymonaco-edtior-wrapper or@typefox/monaco-editor-react to have an editor that is connected to a language server either running in the browser in a web worker orvscode-ws-jsonrpc. is used to an external process via web-socket.
• How different language servers can be intergrated in a common way, so they can communicate via web-socket to the front-end running in the browser.

Thejson-server runs an external Node.jsExpress app where web sockets are used to enable communication between the language server process and the client web application (seeJSON Language Server).Thejson-client contains themonaco-editor-wrapper app which connects to the language server and therefore requires the node server app to be run in parallel.

Thepython-server runs an external Node.jsExpress app where web sockets are used to enable communication between the language server process and the client web application (seePyright Language Server).Thepython-client contains themonaco-editor-wrapper 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, seehere.

Thegroovy-server runs an externalJava app where web sockets are used to enable communication between the language server process and the client web application (Groovy Language Server).Thegroovy-client contains themonaco-editor-wrapper app which connects to the language server and therefore requires the node server app to be run in parallel.

Thejava-server runs an externalJava app where web sockets are used to enable communication between the language server process and the client web application (Java Language Server).Thejava-client contains themonaco-editor-wrapper app which connects to the language server and therefore requires the node server app to be run in parallel.

Langium examples (here client and server communicate viavscode-languageserver-protocol/browser instead of a web socket used in the three examples above

It contains both thelanguage client and thelangauge 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.

Thisexample uses the view service provider from@codingame/monaco-vscode-editor-api to build an application that utilizes more vscode features.Heads up: This is a prototype and still evolving.

It contains both thelanguage client and thelangauge server (web worker). Here you can chose beforehand if the wrapper should be started in classic or extended mode.

It contains both thelanguage client and thelangauge server (web worker).It is also possible to use a@typefox/monaco-editor-react app to connect to the server.

It demostrate how theJSON Language client and language server example can be realised withoutmonaco-editor-wrapper. You find the implementationhere.

It demonstrates how amonaco-editor-wrapper 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.

SeeTypescript Language support.

For thejson-client,react-client or theclient-webpack examples you need to ensure thejson-server example is running:

# start the express server with the language server running in the same process.npm run start:example:server:json

For thepython-client example you need to ensure thepython-server example is running:

# start the express server with the language server running as external node process.npm run start:example:server:python

If you want to use the debugger in thepython-client example you need to the debugger is running. You requiredocker-compose to run it. From the project root rundocker-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. Usedocker-compose -f ./packages/examples/resources/debugger/docker-compose.yml down to stop it.

For thegroovy-client example you need to ensure thegroovy-server example is running. You requiredocker-compose which does not require any manual setup (OpenJDK / Gradle). From the project root rundocker-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. Usedocker-compose -f ./packages/examples/resources/groovy/docker-compose.yml down to stop it.

For thejava-client example you need to ensure thejava-server example is running. You requiredocker-compose which does not require any manual setup (OpenJDK / Eclipse JDT LS). From the project root rundocker-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. Usedocker-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 substantial amount of npm dependencies that pollute the main node_modules dependencies and therefore these examples need to be build and started independently. All verifaction examples re-uses the code form the json client example and therefore require the json server to be started.

• Angular verification example: Before March 2024 this was located ina separate repository. If you want to test it, Please do:cd verify/angular && npm run verify. It serves the client here:http://localhost:4200.

• Next.js verification example: demonstrates how to use@typefox/monaco-editor-react with Next.js, Please do:cd verify/next && npm run verify. It serves the client here:http://localhost:8081.

• 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.

• vite verification example demonstrates how bundling can be achieved with vite. There is no configuration required Please do:cd verify/vite && npm run verify. It serves the client here:http://localhost:8083.

You can as well runvscode tasks to start and debug the server in different modes and the client.

• JSONA Editor:Showcase (GitHub)
• Clangd in Browser:Showcase (GitHub)
• Langium minilogo using monaco-editor-wrapper:Showcase (GitHub)

Whenever you usedmonaco-editor/@codingame/monaco-vscode-editor-apivscode/@codingame/monaco-vscode-extension-api,monaco-languageclient,monaco-editor-wrapper or@typefox/monaco-editor-react ensure they are imported before you do anymonaco-editor orvscode api related intialization work or start using it.

If you use pnpm or yarn, you have to addvscode /@codingame/monaco-vscode-api as direct dependency, otherwise the installation will fail:

"vscode":"npm:@codingame/monaco-vscode-extension-api@~18.1.0"

When you use the libraries from this project you are no longer are required to proxymonaco-editor like"monaco-editor": "npm:@codingame/monaco-vscode-editor-api@~18.1.0" in youpackage.json. You can directly use it like this:

import*asmonacofrom'@codingame/monaco-vscode-editor-api';

If your dependency stack already contains a referencemonaco-editor you must enforce the correct reference to@codingame/monaco-vscode-editor-api or you will have problems with mismatching code. Useoverrides (npm/pnpm) orresolutions (yarn) to do so:

"overrides": {"monaco-editor":"npm:@codingame/monaco-vscode-editor-api@~18.1.0"}

If you have mutiple, possibly hundreds of compile errors resulting from missing functions deep inmonaco-editor orvscode then it is very likely you have a mismatching dependency definition somewhere in your dependency definitions:

1. Usenpm list @codingame/monaco-vscode-api to see if there are two different versions are listed in the dependency tree.
2. If you see a message in the browser console starting withAnother version of monaco-vscode-api has already been loaded. Trying to load then definetly a version mismatch was detected by@codingame/monaco-vscode-api. This error is reported since v14.

If one of the two is true, fix you dependencies, removepackage-lock.json andnode_modules and perform a freshnpm install.

There areVolta instructions in thepackage.json files. When you have Volta available it will ensure the exactly specifiednode andnpm versions are used.

When you are using the vite dev server there are some issues with imports, pleaseread this recommendation.

If you see the problemAssertion failed (There is already an extension with this id) you likely have mismatching dependencies defined forvscode /@codingame/monaco-vscode-extension-api. You should fix this or add the following entry to your vite config:

resolve:{dedupe:['vscode']}

Important: Due to its reliance on@codingame/monaco-vscode-api this stack will not directly work with Server-Side Rendering (SSR) frameworks like Next.js. They client code has to be run in a browser environment. Take a look at theNext.js verification example to see how to dynamically load the code.

@codingame/monaco-vscode-api requires json and other files to be served. In your project's web-server configuration you have to ensure you don't prevent this.

If you see an error similar to the one below:

Uncaught Error:Unexpected non—whitespace character after JSON at position 2SyntaxError:Unexpected non—whitespace character after JSON at position 2at JSON. parse («anonymous>)

It is very likely you have an old version ofbuffer interfering (see#538 and#546). You can enforce a current version by adding aresolution as shown below to your projects'package.json.

"resolutions":{"buffer":"~6.0.3",}

We recommend you now usetypefox/monaco-editor-react.

But if you need to use@monaco-editor/react, then add themonaco-editor import at the top of your editor component filesource:

import*asmonacofrom"monaco-editor";import{loader}from"@monaco-editor/react";loader.config({ monaco});

When webpack is used as bundler there are issues with utilizing the undbundled workers from@codingame/monaco-vscode-api.jhk-mjolner provided a solution in the context of issue #853here:

1. Npm installwebpack-cli (or webpack will do it for you when you try running this later).

2. Create abundle-monaco-workers.js file with this content:

   // solve: __dirname is not defined in ES module scopeimport{fileURLToPath}from'url';import{dirname,resolve}from'path';const__filename=fileURLToPath(import.meta.url);const__dirname=dirname(__filename);exportdefault{entry:{editor:'./node_modules/@codingame/monaco-vscode-editor-api/esm/vs/editor/editor.worker.js',textmate:'./node_modules/@codingame/monaco-vscode-textmate-service-override/worker.js'},output:{filename:'[name].js',path:resolve(__dirname,'./src/assets/monaco-workers'),// if this is true (default), webpack will produce code trying to access global `document` variable for the textmate worker, which will fail at runtime due to being a workerchunkLoading:false},mode:'production',performance:{hints:false}};

3. Add this line to yourpackages.json scripts section:"bundle monaco workers": "webpack --config bundle-monaco-workers.js"

4. Run the scriptnpm run 'bundle monaco workers'

5. Configure theworkerLoaders parameter foruseWorkerFactory to point to the pre-bundled workers:

   'TextEditorWorker':()=>newWorker('/assets/monaco-workers/editor.js',{type:'module'}),'TextMateWorker':()=>newWorker('/assets/monaco-workers/textmate.js',{type:'module'}),

6. Enableeditor.experimental.asyncTokenization in the monaco-wrapper config, if you want to use the textmate worker.

• monaco-languageclient:MIT
• vscode-ws-jsonrpc:MIT
• monaco-editor-wrapper:MIT
• @typefox/monaco-editor-react:MIT
• monaco-languageclient-examples:MIT