LSP and Monaco Integration

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.