Skip to content

LSP and Monaco Integration

Jump to bottom
colin-grant-work edited this page Mar 1, 2022 · 2 revisions

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

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

Documentation

Clone this wiki locally