codemirror-languageservice

Integrate a Language Server Protocol compatible language service into CodeMirror.

Table of Contents

• Installation
• Usage
• API
  • createCompletionSource(options)
  • createHoverTooltipSource(options)
  • createLintSource(options)
  • dispatchTextEdits(view, edits)
  • getTextDocument(state)
  • textDocument(uri?)
• Example
• Compatibility
• Contributing
• Related projects
• License

Installation

This package has peer dependencies on the following packages:

• @codemirror/autocomplete
• @codemirror/language
• @codemirror/lint
• @codemirror/state
• @codemirror/view

Since you will probably import these directly yourself, it’s recommended to install all of them explicitly.

npm install \
  @codemirror/autocomplete \
  @codemirror/language \
  @codemirror/lint \
  @codemirror/state \
  @codemirror/view \
  codemirror-languageservice

Usage

• First, create a CodeMirror EditorView as usual.
• Since LSP is based heavily on files and URIs, you need to add the textDocument() extension to your editor. It’s recommended to pass a file URI. If none is given, a URI is generated that uses the inmemory:// protocol.
• It’s recommended to add a language extension. This is used to detect the languageId for text documents. If this isn’t available, the plaintext language is used.
• Since LSP uses markdown, you need to provide a function to convert markdown to DOM. A good option is to combine hast-util-to-dom, mdast-util-from-markdown, and mdast-util-to-hast.
• Add your language service integrations.

import { autocompletion } from '@codemirror/autocomplete'
import { json } from '@codemirror/lang-json'
import { linter } from '@codemirror/lint'
import { EditorView, hoverTooltip } from '@codemirror/view'
import {
  createCompletionSource,
  createHoverTooltipSource,
  createLintSource,
  textDocument
} from 'codemirror-languageservice'
import { toDom } from 'hast-util-to-dom'
import { fromMarkdown } from 'mdast-util-from-markdown'
import { toHast } from 'mdast-util-to-hast'

import { doComplete, doDiagnostics, doHover } from './my-language-service.js'

function markdownToDom(markdown) {
  const mdast = fromMarkdown(markdown)
  const hast = toHast(mdast)
  return toDom(hast, { fragment: true })
}

const view = new EditorView({
  doc: '',
  parent: document.getElementById('my-editor'),
  extensions: [
    json(),
    textDocument('file:///example.txt'),
    autocompletion({
      override: [createCompletionSource({ doComplete, markdownToDom })]
    }),
    hoverTooltip(createHoverTooltipSource({ doHover, markdownToDom })),
    linter(createLintSource({ doDiagnostics }))
  ]
})

API

createCompletionSource(options)

Create an LSP based completion source.

Options

• doComplete (Function) — Provide LSP completions items.
• markdownToDom (Function) — Convert a markdown string to DOM.
• fromCompletionItemKind (Function, optional) — Convert an LSP completion item kind to a CodeMirror completion type.
• section (string, optional) — The section to use for completions.
• triggerCharacters (string) — Only trigger completions automatically when one of these characters is typed.

Returns

A CodeMirror completion source that uses LSP based completions. (CompletionSource)

createHoverTooltipSource(options)

Create an LSP based hover tooltip provider.

Options

• doHover (Function) — Provide LSP hover info
• markdownToDom (Function) — Convert a markdown string to DOM.

Returns

A CodeMirror hover tooltip source that uses LSP based hover information. (HoverTooltipSource)

createLintSource(options)

Create an LSP based lint source.

By default CodeMirror provides styling for the cm-lintRange-hint, cm-lintRange-info, cm-lintRange-warning, and cm-lintRange-error classes. This extension also uses the cm-lintRange-deprecated and cm-lintRange-unnecessary classes which you may want to style. For example:

.cm-lintRange-deprecated {
  background-image: none !important;
  text-decoration: line-through;
}

.cm-lintRange-unnecessary {
  background-repeat: no-repeat !important;
  opacity: 0.4;
}

Options

• doDiagnostics (Function) — Provide LSP diagnostics
• formatSource (Function, optional) — Format the source of a diagnostic.
• markClass (string, optional) — An additional class for all diagnostics provided by this validation.

Returns

A CodeMirror lint source that uses LSP based diagnostics. (LintSource)

dispatchTextEdits(view, edits)

Apply LSP text edits to an CodeMirror EditorView.

Parameters

• view (EditorView) — The view to dispatch the changes to.
• edits (TextEdit[]) — The edits that should be applied.

getTextDocument(state)

Get the text document for a CodeMirror editor state.

Parameters

• state (EditorState) — The editor state to get the text document for.

Returns

The text document. (TextDocument)

textDocument(uri?)

Assign a text document to an editor state.

This text document is used by other extensions provided by codemirror-languageservice.

The language ID is determined from the name of the language used. If this isn’t found, the language ID defaults to plaintext.

Parameters

• uri (string) —The URI to use for the text document. If this is left unspecified, an auto-incremented inmemory:// URI is used.

Returns

A CodeMirror extension. (Extension)

Example

There’s an example available in the example directory.

Compatibility

This project is compatible with evergreen browsers.

Contributing

This project provides LSP based integrations for CodeMirror. However, not all LSP features map well to CodeMirror. The goal is only to provide integrations that make sense for CodeMirror. If you have a pragmatic idea to integrate another LSP method, feel free to open a new issue.

On top of that, see my general contributing guidelines.

Related projects

• CodeMirror — CodeMirror is a code editor component for the web.
• Language Server Protocol — The Language Server Protocol (LSP) defines the protocol used between an editor or IDE and a language server that provides language features like auto complete, go to definition, find all references etc.
• Transloadit — A simple API to handle any file in your app. codemirror-languageservice was developed as part of the Transloadit JSON editor.

Known language services that you could use this for:

• vscode-css-languageservice — CSS, LESS & SCSS language service extracted from VSCode to be reused.
• vscode-html-languageservice — Language services for HTML.
• vscode-json-languageservice — JSON language service extracted from VSCode to be reused.
• vscode-markdown-languageservice — The language service that powers VS Code’s Markdown support.
• yaml-language-server — Language Server for YAML Files.
• @tailwindcss/language-service — About Intelligent Tailwind CSS tooling.
• @volar/language-service — The Embedded Language Tooling Framework.

License

MIT © Remco Haszing