The @theia/monaco
extension contributes the integration of the monaco-editor.
This includes:
- full-feature code editor
- diff-editor
- code snippets
- textmate grammars (theme registry, service)
This package is intended to be the interface between the @theia/monaco-editor-core
package, the project's bundling of the monaco-editor-core
package published by the VSCode
team, and the rest of the application. When we uplift to a new version of monaco-editor-core
, this package will need to be checked particularly thoroughly. To facilitate that
process, the steps for undertaking a Monaco uplift are outlined here.
- Clone the VSCode repo and make sure you have the following remotes:
- https://github.com/microsoft/vscode.git - the official VSCode repo.
- https://github.com/theia-ide/vscode.git - Theia's fork.
- Find the latest release tag in the official VSCode repo, and the most recent uplift branch in the Theia fork.
At the time of this writing the latest release tag is
1.67.2
, and the uplift branch ismonaco-uplift-2022-6
- Check out the release tag, cherry pick the tip of the uplift branch, and resolve any conflicts.
As you resolve conflicts and make changes to the VSCode repo, make sure you end up with a single commit on the uplift branch to make it easier for the next person to rebase.
- Try to build. At the moment, this means running
yarn
andyarn run gulp editor-distro
. - Fix any build errors that arise.
- Change the version in
build/monaco/package.json
- build/gulpfile.editor.js: various changes to modify the treeshaking and output destinations.
- build/lib/standalone.js/ts: changes to output sourcemaps etc. One small change to fix a build error due to having a directory named
model
and a file namedmodel.ts
in the same folder. - src/vs/base/browser/dompurify/dompurify.js changes for CommonJS rather than ESM
- src/vs/base/common/marked/marked.js changes for CommonJS rather than ESM
For initial testing, it's easier to point dependencies to your local VSCode.
- Having built
monaco-editor-core
using the steps above. - Find all references to
@theia/monaco-editor-core
inpackage.json
s and replace their version with"link:<path to your local build of monaco-editor-core>"
.
Using
link:
means that if you subsequently make changes on the VSCode side, you only need to rebuild VSCode and then rebuild Theia to see the effects.
- Delete your
node_modules
andyarn
and build Theia. - Fix any build errors.
- Uncomment the
bindMonacoPreferenceExtractor
function inexamples/api-samples/src/browser/monaco-editor-preferences/monaco-editor-preference-extractor.ts
and run the commands there. Fix theEditorGeneratedPreferenceSchema
as necessary, and add or remove validations from theMonacoFrontendApplicationContribution
as appropriate. - Look for comments that indicate forced types or other code smells that would prevent a build error from being thrown where it should be thrown and check that the assertion still applies.
If you add these, mark them with @monaco-uplift - that'll make them easier to find in the future. Better: if you can remove them, do! Typically, the cause is mixing imports from private API and public API. Often public API fails to satisfy private declarations.
- Test the application thoroughly - make sure everything's still working.
It may also be necessary to update our various
vscode
dependencies to match the current state of VSCode. It may not be necessary to upgrade all (or any) of these to successfully adopt a new Monaco version, but if something is misbehaving inexplicably, checking dependencies is a reasonable place to start. Check on:
vscode-debugprotocol
vscode-languageserver-protocol
vscode-oniguruma
vscode-proxy-agent
vscode-ripgrep
vscode-textmate
vscode-uri
Once you believe that everything is in working order, you'll need to publish the new @theia/monaco-editor-core
for testing. The instructions for doing so are
here. Once the package is published, point your package.json
s at the testing version and make
sure everything still works, then make a PR.
- Eclipse Public License 2.0
- 一 (Secondary) GNU General Public License, version 2 with the GNU Classpath Exception
"Theia" is a trademark of the Eclipse Foundation https://www.eclipse.org/theia
See here for a detailed documentation.