-
Notifications
You must be signed in to change notification settings - Fork 2.5k
LSP and Monaco Integration
colin-grant-work edited this page Mar 1, 2022
·
2 revisions
This document explains how LSP and Monaco are integrated together in Theia.
- VS Code Language Client
- Microsoft/vscode-languageclient allows VS Code extensions to integrate language servers adhering to the language server protocol (LSP).
- We've decided to reuse it instead of implementing and maintaining custom Monaco language client, since LSP apis are very close to VS Code and Monaco apis.
- JSON RPC over Web Socket
- TypeFox/vscode-ws-jsonrpc implements communication between a JSON RPC client and server over WebSocket based on Microsoft/vscode-jsonrpc.
- Monaco Language Client
- TypeFox/monaco-languageclient allows Monaco editor to integrate language servers adhering to the LSP.
- For LSP, it has runtime dependencies only to vscode-languageclient. In practice, it's always used in the browser context, so end clients should use vscode-ws-jsonrpc as well in order to communicate with language servers running on the backend via web-sockets. In order to ensure that, the repository comes with an example depending on local version of Monaco language client and vscode-ws-jsonrpc.
- For Monaco, it does not have runtime dependencies in order to allow alternative Monaco distribution:
- It uses Microsoft/monaco-editor-core as a dev dependency in order to get access to Monaco apis at compilation time.
- Microsoft/monaco-editor-core is a minimal official distribution. It does not include any language grammar or smartness contributions.
- An example in the repo is using Microsoft/monaco-editor-core as a runtime dependency for the demonstration purposes.
- Theia
- Theia is using TypeFox/monaco-editor-core distribution that does not contain any language contributions as Microsoft/monaco-editor, and not tree shaken as Microsoft/monaco-editor-core:
- We are not interested in Monaco grammars and smartness for languages like css, js/ts, json and so on, because we define grammars with TextMate for VS Code compatibility and provide language smartness via LSP.
- We don't need tree shaking because we want to consume a bit more than just Monaco from VS Code repository in order to reuse complete functionality of the quick palette and other services for VS Code compatibility.
- Monaco integration logic should be encapsulated into
@theia/monaco
extension and not used lightly in other extensions, since we rely on internal VS Code apis. During the upgrade it should be enough to update this extension. - End clients should work with Monaco agnostic apis, like
@theia/editor
that provides apis similar to Monaco but based on stable LSP apis.@theia/monaco
extension is responsible for conversions between LSP and Monaco apis. - Monaco, VS Code and LSP apis are generally very close with a difference that positions in Monaco are 1-based, but 0-based in VS Code and LSP.
- Theia is using TypeFox/monaco-editor-core distribution that does not contain any language contributions as Microsoft/monaco-editor, and not tree shaken as Microsoft/monaco-editor-core:
Layer | API | Uses |
---|---|---|
@theia/plugin-ext(-vscode) |
VS Code <-> LSP VS Code <-> Monaco |
vscode-languageserver-protocol vscode @theia/monaco and its dependent |
@theia/editor and its clients |
LSP | vscode-languageserver-protocol |
@theia/monaco |
LSP <-> Monaco |
@theia/editor vscode-languageserver-protocol monaco-editor-core monaco-languageclient
|
Monaco language client | Monaco <-> LSP LSP <-> VS Code |
vscode vscode-languageserver-protocol monaco-editor-core vscode-languageclient
|
VS Code language client | VS Code <-> LSP |
vscode vscode-languageserver-protocol
|
Language server (JS/TS, Java and so on) | LSP <-> language | vscode-languageserver-protocol |
- Upgrade vscode-ws-jsonrpc to latest vscode-jsonrpc.
- Upgrade monaco-languageclient to the latest vscode-languageclient and vscode-ws-jsonrpc.
- Upgrade monaco-languageclient to the latest Microsoft/monaco-editor-core.
- Upgrade TypeFox/monaco-editor-core to the latest Microsoft/monaco-editor-core.
- Upgrade Theia to the latest monaco-languageclient and TypeFox/monaco-editor-core.
- See https://github.com/theia-ide/theia/pull/5901#issue-305955861 for testing guidance.
- test language features with VS Code extension:
- test that features are available in the editor context menu and in quick command palette (automated)
- a declaration is revealed when following the reference (automated)
- focus belongs to a proper editor after following a reference (for internal and outside references, from editor to editor preview and view versa) (automated)
- reference peek is still opened after following a reference (for internal and outside references, from editor to editor preview and view versa) (automated)
- esc closes reference peek widget (automated)
- completion items are properly resolved and inserted (automated)
- focus belongs to a proper editor on peek definition (for internal and outside references, from editor to editor preview and view versa) (automated)
- check that rename work inside the file and across files (automated)
- check that arguments are proposed by the signature help (automated)
- check that hover is present with properly rendered docs (automated)
- check that symbol occurrences is highlighted when a declaration or reference is selected (automated)
- check that go to (type|implementation) definition works properly, i.e. definition is revealed (automated)
- check that code lens work properly (automated)
- run/debug code lenses: https://github.com/kasecato/vscode-javadebug-sample. One has to install vscode java, debug and test extensions.
- check that code actions work properly (quick fixes) (automated)
- check that document and selection formatting work properly (automated)
- check color provider with css colors
- check link provider with links in html
- check that folding ranges are properly provided for js, css and html
- check go to symbol command
- check open workspace symbol command
- test quick palette:
- proper keys are displayed for the quick command palette, i.e. they are displayed and a corresponding Monaco command can be triggered by such keybinding
- use sample vscode extension
- use fuzzy search
- test vscode tree view (that context keys work properly)
- test plugin editor decorations, for example with power mode extension
- test debug console input editor
- test debug breakpoint editor
- test that preferences are propagated as config key values: change editor preferences and check whether they are reflected
- test language auto detection
- test
edit
menu with editor - test
selection
menu with editor - test editor context menu
- smoke test some VS Code extensions like go, python, just use editor for a bit, check backend and frontend logs for errors
- test manually task related functionality https://github.com/eclipse-theia/theia/pull/7149#issuecomment-604067026
Project Management
- Roadmap
- Dev Meetings
- Technical Meetings
- Community Call
- Intellectual Property (IP) guide
- Registering CQs (Deprecated)
Documentation