Update README, especially Troubleshooting and examples.

- Update dates in CHANGELOGs

Author: kaisalmen

README.md

@@ -45,13 +45,15 @@ The examples not requiring a backend are now available [via GitHub Pages](https:
       - [Server processes](#server-processes)
         - [JSON Language Server](#json-language-server)
         - [Pyright Language Server](#pyright-language-server)
+        - [Graalpy Debugger](#graalpy-debugger)
         - [Groovy Language Server](#groovy-language-server)
         - [Java Language Server](#java-language-server)
     - [Verification Examples \& Usage](#verification-examples--usage)
     - [VSCode integration](#vscode-integration)
   - [Featured projects](#featured-projects)
   - [Troubleshooting](#troubleshooting)
     - [General](#general)
+    - [@codingame/monaco-vscode-editor-api / monaco-editor usage](#codingamemonaco-vscode-editor-api--monaco-editor-usage)
     - [Dependency issues: monaco-editor / @codingame/monaco-vscode-api / @codingame/monaco-vscode-editor-api](#dependency-issues-monaco-editor--codingamemonaco-vscode-api--codingamemonaco-vscode-editor-api)
     - [Volta](#volta)
     - [Vite dev server troubleshooting](#vite-dev-server-troubleshooting)
@@ -60,7 +62,6 @@ The examples not requiring a backend are now available [via GitHub Pages](https:
     - [Bad Polyfills](#bad-polyfills)
       - [buffer](#buffer)
     - [monaco-editor and react](#monaco-editor-and-react)
-    - [pnpm](#pnpm)
   - [Licenses](#licenses)
 
 ## Changelogs, project history and compatibility
@@ -137,7 +138,7 @@ The **json-client** contains the [monaco-editor-wrapper app](./packages/examples
 
 The **python-server** runs an external Node.js [Express app](./packages/examples/src/python/server/main.ts) where web sockets are used to enable communication between the language server process and the client web application (see [Pyright Language Server](#pyright-language-server)).
 The **python-client** contains the [monaco-editor-wrapper app](./packages/examples/src/python/client/main.ts) 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](./packages/examples/src/python/client/reactPython.tsx) to connect to the server.
+   It is also possible to use a [@typefox/monaco-editor-react app](./packages/examples/src/python/client/reactPython.tsx) to connect to the server. Both versions now feature a debugger, see [here](#graalpy-debugger).
 
 #### Groovy Language client and language server example ([Location](./packages/examples/src/groovy))
 
@@ -200,6 +201,10 @@ For the **python-client** example you need to ensure the **python-server** examp
 npm run start:example:server:python
 ```
 
+##### Graalpy Debugger
+
+If 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.
+
 ##### Groovy Language Server
 
 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.
@@ -214,15 +219,11 @@ None of the verification examples is part of the npm workspace. Some bring subst
 
 - [Angular verification example](./verify/angular): Before March 2024 this was located in [a separate repository](https://github.com/TypeFox/monaco-languageclient-ng-example). If you want to test it, Please do: `cd verify/angular && npm run verify`. It serves the client here: <http://localhost:4200>.
 
-- [webpack verification example](./verify/webpack) demonstrates how bundling can be achieved with webpack. You find the configuration here: [webpack.config.js](./verify/webpack/webpack.config.js). Please do: `cd verify/webpack && npm run verify`. It serves the client here: <http://localhost:8081>.
-
-- [vite verification example](./verify/vite) 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:8082>.
+- [Next.js verification example](./verify/next): 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>.
 
-- [pnpm verification example](./verify/pnpm) demonstrates that the project can be build with vite, but pnpm is used instead of npm. Please do: `cd verify/pnpm && pnpm run verify`. It serves the client here: <http://localhost:8083>.
+- [webpack verification example](./verify/webpack) demonstrates how bundling can be achieved with webpack. You find the configuration here: [webpack.config.js](./verify/webpack/webpack.config.js). Please do: `cd verify/webpack && npm run verify`. It serves the client here: <http://localhost:8082>.
 
-- [yarn verification example](./verify/yarn) demonstrates that the project can be build with vite, but yarn is used instead of npm. Please do: `cd verify/yarn && yarn run verify`. It serves the client here: <http://localhost:8083>.
-
-- [Next.js verification example](./verify/next): 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:8084>.
+- [vite verification example](./verify/vite) 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>.
 
 ### VSCode integration
 
@@ -238,11 +239,38 @@ You can as well run [vscode tasks](./.vscode/launch.json) to start and debug the
 
 ### General
 
-Whenever you used `monaco-editor`, `vscode`, `monaco-languageclient`, `monaco-editor-wrapper` or `@typefox/monaco-editor-react` ensure they are imported before you do any `monaco-editor` or `vscode` api related intialization work or start using it. Please check the [our python language client example](./packages/examples/src/python/client/main.ts) to see how it should be done.
+Whenever you used `monaco-editor`/`@codingame/monaco-vscode-editor-api` `vscode`/`@codingame/monaco-vscode-extension-api`, `monaco-languageclient`, `monaco-editor-wrapper` or `@typefox/monaco-editor-react` ensure they are imported before you do any `monaco-editor` or `vscode` api related intialization work or start using it.
+
+If you use pnpm or yarn, you have to add `vscode` / `@codingame/monaco-vscode-api` as direct dependency, otherwise the installation will fail:
+
+```json
+"vscode": "npm:@codingame/monaco-vscode-extension-api@~14.0.4"
+```
+
+### @codingame/monaco-vscode-editor-api / monaco-editor usage
+
+When you use the libraries from this project you are no longer are required to proxy `monaco-editor` like `"monaco-editor": "npm:@codingame/monaco-vscode-editor-api@~14.0.4"` in you `package.json`. You can directly use it like this:
+
+```js
+import * as monaco from '@codingame/monaco-vscode-editor-api';
+```
+
+If your dependency stack already contains a reference `monaco-editor` you must enforce the correct reference to `@codingame/monaco-vscode-editor-api` or you will have problems with mismatching code. Use`overrides` (npm/pnpm) or `resolutions` (yarn) to do so:
+
+```json
+"overrides": {
+  "monaco-editor": "npm:@codingame/monaco-vscode-editor-api@~14.0.4"
+}
+```
 
 ### Dependency issues: monaco-editor / @codingame/monaco-vscode-api / @codingame/monaco-vscode-editor-api
 
-If you have mutiple, possibly hundreds of compile errors resulting from missing functions deep in `monaco-editor` or `vscode` then it is very likely your `package-lock.json` or `node_modules` are dirty. Remove both and do a fresh `npm install`. Always `npm list monaco-editor` is very useful. If you see different or errornous versions, then this is an indicator something is wrong.
+If you have mutiple, possibly hundreds of compile errors resulting from missing functions deep in `monaco-editor` or `vscode` then it is very likely you have a mismatching dependency definition somewhere in your dependency definitions:
+
+1. Use `npm 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 with `Another 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, remove `package-lock.json` and `node_modules` and perform a fresh `npm install`.
 
 ### Volta
 
@@ -252,7 +280,7 @@ There are [Volta](https://volta.sh/) instructions in the `package.json` files. W
 
 When you are using the vite dev server there are some issues with imports, please [read this recommendation](https://github.com/CodinGame/monaco-vscode-api/wiki/Troubleshooting#if-you-use-vite).
 
-If you see the problem *Assertion failed (There is already an extension with this id)* you likely have mismatching dependencies defined for `vscode` / `@codingame/monaco-vscode-api`. You should fix this or add the following entry to your vite config:
+If you see the problem *Assertion failed (There is already an extension with this id)* you likely have mismatching dependencies defined for `vscode` / `@codingame/monaco-vscode-extension-api`. You should fix this or add the following entry to your vite config:
 
 ```javascript
 resolve: {
@@ -262,7 +290,7 @@ resolve: {
 
 ### SSR frameworks
 
-**Important:** Due to its reliance on `monaco-editor` and `@codingame/monaco-vscode-api` this stack will very likely not work with Server-Side Rendering (SSR) frameworks. They client code has to be run in a browser environment.
+**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 the [Next.js verification example](./verify/next) to see how to dynamically load the code.
 
 ### Serve all files required
 
@@ -302,22 +330,6 @@ import { loader } from "@monaco-editor/react";
 loader.config({ monaco });
 ```
 
-Because `@codingame/monaco-vscode-api` relies on it own build of `monaco-editor` it may be required to enforce the `monaco-editor` version via `overrides` (npm/pnpm) or `resolutions` (yarn):
-
-```json
-"overrides": {
-  "monaco-editor": "npm:@codingame/monaco-vscode-editor-api@~14.0.4"
-}
-```
-
-### pnpm
-
-If you use pnpm, you have to add `vscode` / `@codingame/monaco-vscode-api` as direct dependency (you find the [compatibility table here](https://github.com/TypeFox/monaco-languageclient/blob/main/docs/versions-and-history.md#monaco-editor--codingamemonaco-vscode-api-compatibility-table), otherwise the installation will fail.
-
-```json
-"vscode": "npm:@codingame/monaco-vscode-extension-api@~14.0.4"
-```
-
 ## Licenses
 
 - monaco-languageclient: [MIT](https://github.com/TypeFox/monaco-languageclient/blob/main/packages/client/LICENSE)

docs/versions-and-history.md

@@ -6,7 +6,7 @@ The following table describes which version of **monaco-languageclient** and **@
 
 | monaco-languageclient | monaco-editor-wrapper | monaco-editor-react | monaco-vscode-api / editor-api | vscode | monaco-editor | release date | comment |
 | :---- | :---- | :--- | :--- | :--- | :--- | :--- | :--- |
-| 9.4.0 | 6.4.0 | 6.4.0 | 14.0.4 | 1.97.2 | 0.52.2 | 2025-02-1x | |
+| 9.4.0 | 6.4.0 | 6.4.0 | 14.0.4 | 1.97.2 | 0.52.2 | 2025-02-17 | |
 | 9.3.0 | 6.3.0 | 6.3.0 | 14.0.2 | 1.97.0 | 0.52.2 | 2025-02-12 | |
 | 9.2.5 | 6.2.5 | 6.2.5 | 13.1.6 | 1.96.4 | 0.52.2 | 2025-02-08 | |
 | 9.2.4 | 6.2.4 | 6.2.4 | 13.1.4 | 1.96.4 | 0.52.2 | 2025-02-06 | |

index.html

@@ -102,21 +102,15 @@ <h3>Angular</h2>
         Please start  <b><code>cd verify/angular && npm run verify</code></b> beforehand:<br>
         <a href="http://localhost:4200">JSON Language Client & Language Server (Web Socket) (Angular Dev Server)</a>
         <h3>Next.js</h3>
-        Please start  <b><code>cd verify/next && npm run verify</code></b> beforehand:<br>
-        <a href="http://localhost:8084">JSON Language Client & Language Server (Web Socket) (Next.js Dev Server)</a>
+        Please start <b><code>cd verify/next && npm run verify</code></b> beforehand:<br>
+        <a href="http://localhost:8081">JSON Language Client & Language Server (Web Socket) (Next.js Dev Server)</a>
         <h3>Webpack</h3>
-        Please start  <b><code>cd verify/webpack && npm run verify</code></b> beforehand:<br>
-        <a href="http://localhost:8081">JSON Language Client & Language Server (Web Socket) (webpack build)</a>
+        Please start <b><code>cd verify/webpack && npm run verify</code></b> beforehand:<br>
+        <a href="http://localhost:8082">JSON Language Client & Language Server (Web Socket) (webpack build)</a>
         <h3>Vite</h3>
-        Please start  <b><code>cd verify/vite && npm run verify</code></b> beforehand:<br>
-        <a href="http://localhost:8082">JSON Language Client & Language Server (Web Socket) (vite build)</a>
-        <h3>Pnpm/vite</h3>
-        Please start  <b><code>cd verify/pnpm && pnpm run verify</code></b> beforehand:<br>
-        <a href="http://localhost:8083">JSON Language Client & Language Server (Web Socket) (pnpm/vite build)</a>
-        <h3>Yarn/vite</h3>
-        Please start  <b><code>cd verify/yarn && yarn run verify</code></b> beforehand:<br>
-        <a href="http://localhost:8083">JSON Language Client & Language Server (Web Socket) (yarn/vite build)</a>
-    </div>
+        Please start <b><code>cd verify/vite && npm run verify</code></b> beforehand:<br>
+        <a href="http://localhost:8083">JSON Language Client & Language Server (Web Socket) (vite build)</a>
+        </div>
 </body>
 
 </html>

package-lock.json

@@ -19,8 +19,8 @@
     "@stylistic/eslint-plugin": "~3.1.0",
     "@testing-library/react": "~16.2.0",
     "@types/node": "~22.13.4",
-    "@types/react": "~19.0.8",
-    "@types/react-dom": "~19.0.3",
+    "@types/react": "~19.0.10",
+    "@types/react-dom": "~19.0.4",
     "@typescript-eslint/eslint-plugin": "~8.24.0",
     "@typescript-eslint/parser": "~8.24.0",
     "@vitejs/plugin-react": "~4.3.4",

package.json

@@ -2,7 +2,7 @@
 
 All notable changes to this npm module are documented in this file.
 
-## [9.4.0] - 2025-02-1x
+## [9.4.0] - 2025-02-17
 
 - Handle languageclient errors cases more robustly [#859](https://github.com/TypeFox/monaco-languageclient/pull/859)
 - Updated all `@codingame/monaco-vscode` packages to `14.0.4`.

packages/client/CHANGELOG.md

@@ -2,7 +2,7 @@
 
 All notable changes to this npm module are documented in this file.
 
-## [2025.2.6] - 2025-02-1x
+## [2025.2.6] - 2025-02-17
 
 - Handle languageclient errors cases more robustly [#859](https://github.com/TypeFox/monaco-languageclient/pull/859)
 - Updated all `@codingame/monaco-vscode` packages to `14.0.4`.

packages/examples/CHANGELOG.md

@@ -2,7 +2,7 @@
 
 All notable changes to npm module [@typefox/monaco-editor-react](https://www.npmjs.com/package/@typefox/monaco-editor-react) are documented in this file.
 
-## [6.4.0] - 2025-02-1x
+## [6.4.0] - 2025-02-17
 
 - refactor: replace all useEffect and useCallback with one useEffect [#862](https://github.com/TypeFox/monaco-languageclient/pull/862)
 - Handle languageclient errors cases more robustly [#859](https://github.com/TypeFox/monaco-languageclient/pull/859)

packages/wrapper-react/CHANGELOG.md

@@ -24,7 +24,7 @@ import { WrapperConfig } from 'monaco-editor-wrapper';
 import { MonacoEditorReactComp } from '@typefox/monaco-editor-react';
 
 const wrapperConfig: WrapperConfig = {
-  $type: 'extendend',
+  $type: 'extended',
   htmlContainer: document.getElementById('monaco-editor-root')!,
   editorAppConfig: {
     codeResources: {

packages/wrapper-react/README.md

@@ -2,7 +2,7 @@
 
 All notable changes to npm module [monaco-editor-wrapper](https://www.npmjs.com/package/monaco-editor-wrapper) are documented in this file.
 
-## [6.4.0] - 2025-02-1x
+## [6.4.0] - 2025-02-17
 
 - Handle languageclient errors cases more robustly [#859](https://github.com/TypeFox/monaco-languageclient/pull/859)
 - Updated all `@codingame/monaco-vscode` packages to `14.0.4`.

packages/wrapper/CHANGELOG.md

@@ -3,8 +3,8 @@
   "scripts": {
     "verify": "npm install && npm run dev",
     "verify:ci": "npm install && npm run build -d",
-    "dev": "next dev -p 8084",
-    "dev:turbo": "next dev --turbopack -p 8084",
+    "dev": "next dev -p 8081",
+    "dev:turbo": "next dev --turbopack -p 8081",
     "build": "next build",
     "start": "next start",
     "clean": "shx rm -fr dist .next *.tsbuildinfo"

verify/next/package.json

@@ -20,7 +20,6 @@
   },
   "scripts": {
     "build": "tsc --build tsconfig.json",
-    "showconfig": "tsc --showconfig",
     "verify:ci": "npm install && npm run build"
   }
 }

verify/peerNpm/package.json

@@ -20,7 +20,6 @@
   },
   "scripts": {
     "build": "tsc --build tsconfig.json",
-    "showconfig": "tsc --showconfig",
     "verify:ci": "pnpm install && pnpm run build"
   }
 }

verify/peerPnpm/package.json

@@ -32,7 +32,6 @@
   },
   "scripts": {
     "build": "tsc --build tsconfig.json",
-    "showconfig": "tsc --showconfig",
     "verify:ci": "yarn install && yarn run build"
   }
 }

verify/peerYarn/package.json

@@ -7,7 +7,7 @@ import { defineConfig } from 'vite';
 
 export default defineConfig({
     preview: {
-        port: 8082
+        port: 8083
     },
     worker: {
         format: 'es'

verify/vite/vite.config.ts

@@ -29,6 +29,6 @@
     "clean": "shx rm -fr dist *.tsbuildinfo",
     "build:msg": "echo Building client-webpack example:",
     "build": "npm run build:msg && npm run clean && webpack",
-    "start": "http-server ./ --port 8081"
+    "start": "http-server ./ --port 8082"
   }
 }