This document explains how LSP and Monaco are integrated together in Theia.

Components

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

Layers

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

Migration Guidelines

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

Testing a Monaco Uplift (drawn from #7149)

• 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