@jvalue/jayvee-monaco
v0.6.3
Published
<!-- SPDX-FileCopyrightText: 2023 Friedrich-Alexander-Universitat Erlangen-Nurnberg
Downloads
390
Readme
@jvalue/monaco-editor
This library contains a React component that will spawn an instance of the Monaco Editor. This instance can only be used to edit Jayvee language files.
How to use the component
Install both the monaco editor and the language server via npm
:
npm install @jvalue/monaco-editor @jvalue/language-server-web-worker
Enable Web Workers in your React project as the language server will run in its own Web Worker.
Open tsconfig.json
and add "WebWorker" to the lib array:
{
"compilerOptions": {
- "lib": ["dom", "dom.iterable", "esnext"],
+ "lib": ["dom", "dom.iterable", "esnext", "WebWorker"],
}
}
The following sample code spawns an instance of the monaco editor and runs the corresponding language server in a separate Web Worker:
import { MonacoEditor } from '@jvalue/jayvee-monaco';
import React from 'react';
function startJayveeWorker(): Worker {
const worker = new Worker(
// TODO adjust the path / URL to the language server:
new URL('<path-to-language-server-web-worker>/main.js', import.meta.url), {
type: 'module',
});
return worker;
}
export const EditorExample: React.FC = () => {
return (
<div style={{ height: '500px' }}>
<MonacoEditor
startJayveeWorker={startJayveeWorker}
editorText={'Add example code here'}
onDidChangeEditorText={(newText): void => console.log(newText)}
/>
</div>
);
};
In case you bundle your React app with webpack, you are able to use a hard-coded relative path to the main.js
file
included in @jvalue/language-server-web-worker
.
Such a path looks like ../../node_modules/@jvalue/language-server-web-worker/main.js
but probably needs
slight adjustments, so it navigates to the desired file location.
Alternatively, you can host the main.js
file of @jvalue/language-server-web-worker
and make it available under a
certain URL.
Then, you can use that URL for instantiating the Web Worker instead of the previously mentioned file path.
Development set-up
The following guide explains how to install this component without relying on a npm registry or the like. This is particularly useful to manually test the component locally before publishing it.
Prerequisites
We expect the component to be used in a (default) Create-React-App project. This project should ideally be created outside of the directory where the Jayvee repository is stored.
Build the language server Web Worker
The language-server-web-worker
project provides a ready-to-use language server to be run in a Web
Worker.
It is required by the monaco editor in order to provide features like autocompletion and code diagnostics.
Build the project using
npx nx build language-server-web-worker
This creates a file main.js
in the folder <jayvee project root>/dist/apps/language-server-web-worker
which is
required in a later step.
Building and packing the monaco editor
To build and pack the monaco editor, navigate to the project root folder and run
npx nx pack @jvalue/monaco-editor
Now, in the directory <jayvee project
root>/dist/libs/monaco-editor
, you will find a file named monaco-editor-<version>.tgz
with <version>
being the version of the monaco editor package.
We want to be able to use the package in another project. To make the package behave as if it was directly pulled
from a registry, we first want to pack it. To do this, run npm pack
in the directory <jayvee project
root>/dist/libs/monaco-editor
.
Now, you will find a file named jvalue-monaco-editor-<version>.tgz
in that directory,
with <version>
being the version of the monaco editor package.
Installation of the monaco editor
We want to be able to use the package in the React project as if it was directly pulled
from a registry. To achieve that, switch to the React project where you want to test the editor. Open package.json
and add the following dependency:
"dependencies": {
"@jvalue/jayvee-monaco": "file:../../../jayvee/dist/libs/monaco-editor/jvalue-monaco-editor-0.0.0.tgz"
},
You might have to adjust the paths to the files (and especially the version at the end).
Now, run npm install
.
Tip: Whenever you create a new version of the packages using
npm pack
, you have to install them again. This sometimes results in errors regarding the package integrity, because the two packages will contain new content, leading to a new hash. A fairly easy way to deal with this is to uninstall the two packages (i.e. to remove them from the dependencies and to callnpm install
), and then to re-install them. If you need to do this frequently, you could also symlink the packages directly, but this might require you to install the peer dependencies manually. Another important point: CreateReactApp seems to cache the build output a bit too aggressively in some cases. After installing a new version of the package, you might need to deletenode_modules/.cache/
.
Enable Web Workers
Furthermore, we need to enable Web Workers in the React project. Open tsconfig.json
and add "WebWorker" to the
lib array:
{
"compilerOptions": {
- "lib": ["dom", "dom.iterable", "esnext"],
+ "lib": ["dom", "dom.iterable", "esnext", "WebWorker"],
}
}
Create the actual editor
Now, create a new file my-editor.tsx
where the actual editor will be contained. Add the following file content:
import { MonacoEditor } from '@jvalue/jayvee-monaco';
import React from 'react';
const exampleCode = 'Add example code here';
function startJayveeWorker(): Worker {
// TODO adjust the path to the language server:
const worker = new Worker(new URL('<jayvee project root>/dist/apps/language-server-web-worker/main.js', import.meta.
url), {
type: 'module',
});
return worker;
}
export const EditorExample: React.FC = () => {
return (
<div style={{ height: '500px' }}>
<MonacoEditor
startJayveeWorker={startJayveeWorker}
editorText={exampleCode}
onDidChangeEditorText={(newText): void => console.log(newText)}
/>
</div>
);
};
Make sure to adjust the path of the URL so it refers to the
main.js
file of the built language server created earlier.
That's it! You can now use the editor in your React project.
Source Maps warnings
When compiling your React project, you might get a large number of Webpack warnings, saying that Source Maps from vscode-languageserver
cannot be parsed. It is not clear why this is happening. Maybe, this is related to https://github.com/microsoft/vscode-languageserver-node/issues/879 and https://github.com/microsoft/vscode-languageserver-node/pull/908 (even though these issues seem to be resolved).
Development notes
Webpack URLs
When using new URL('something')
, Webpack uses static analysis to bundle the referenced item. So this is not just
runtime code - it is used during compilation. It was mentioned somewhere in the long discussion here:
https://github.com/webpack/webpack/discussions/13655#discussioncomment-937300. Also refer to the corresponding webpack documentation.
Resources
The following resources were pretty useful when building the component:
- https://github.com/eclipse-theia/theia/wiki/LSP-and-Monaco-Integration
- https://github.com/TypeFox/monaco-languageclient (includes an example regarding the in-browser LSP, see https://github.com/TypeFox/monaco-languageclient/blob/c5511b19e95e237c3f95a0fc0588769263f3ba40/packages/examples/browser-lsp/src)