codemirror-languageserver

Language Server Plugin for CodeMirror 6

This plugin connects a CodeMirror 6 editor with a Language Server over WebSocket, providing IDE-like features in the browser.

How It Works | Live Demo

Features

https://user-images.githubusercontent.com/348107/120141150-c6bb9180-c1fd-11eb-8ada-9b7b7a1e4ade.mp4

• ⌨️ Code Completion (w/ Resolve Support)
• 📚 Hover Documentation
• 🩺 Diagnostics
• 🔍 Go to Definition, Declaration, and Type Definition
• 🔦 Document Highlight
• 🎨 Document Formatting and Range Formatting
• ✏️ Rename Symbol

Installation

npm i codemirror-languageserver

Peer dependencies: This package requires @codemirror/autocomplete, @codemirror/lint, @codemirror/state, and @codemirror/view as peer dependencies. If you're using CodeMirror 6, you likely already have these installed.

Quick Start

import { EditorState } from '@codemirror/state';
import { EditorView } from '@codemirror/view';
import { languageServer } from 'codemirror-languageserver';

const ls = languageServer({
    serverUri: 'ws://localhost:8080',
    rootUri: 'file:///',
    documentUri: `file:///${filename}`,
    languageId: 'cpp', // As defined at https://microsoft.github.io/language-server-protocol/specification#textDocumentItem.
});

const view = new EditorView({
    state: EditorState.create({
        extensions: [
            // ... other extensions
            ls,
        ],
    }),
});

This sets up all built-in features: completion, hover, diagnostics, go-to-definition, document highlight, and rename support.

Options

Option	Type	Description
serverUri	ws://... or wss://...	WebSocket server URI
rootUri	string	Root URI of the workspace
workspaceFolders	WorkspaceFolder[]	LSP workspace folders
documentUri	string	URI of the document being edited
languageId	string	Language identifier (spec)
initializationOptions	object	Server-specific initialization options
locale	string	Locale for the LSP session (e.g. 'en')
allowHTMLContent	boolean	Trust raw HTML in hover/completion content (default: false)
synchronizationMethod	SynchronizationMethod	'full' or 'incremental' document sync (default: 'full')
client	LanguageServerClient	Share a client across multiple editor instances
onCapabilities	(capabilities) => void	Called when server capabilities are available
onError	(error: Error) => void	Called when the connection encounters an error
onClose	() => void	Called when the connection is closed

Error Handling

The plugin does not crash on connection failures. Use onError and onClose to handle disconnections:

languageServer({
    serverUri: 'ws://localhost:8080',
    rootUri: 'file:///',
    documentUri: `file:///${filename}`,
    languageId: 'cpp',
    onError(error) {
        console.error('LSP error:', error);
    },
    onClose() {
        console.log('LSP connection closed');
        // Recreate the editor extensions to reconnect
    },
})

Shared Client

To share the same language server connection across multiple editor instances:

import { LanguageServerClient, languageServerWithTransport, WebSocketTransport } from 'codemirror-languageserver';

const client = new LanguageServerClient({
    transport: new WebSocketTransport('ws://localhost:8080'),
    rootUri: 'file:///',
});

// Use the same client for multiple editors
const ls1 = languageServerWithTransport({
    client,
    documentUri: 'file:///main.cpp',
    languageId: 'cpp',
});

const ls2 = languageServerWithTransport({
    client,
    documentUri: 'file:///utils.cpp',
    languageId: 'cpp',
});

Custom Transport

Use languageServerWithTransport for non-WebSocket connections:

import { languageServerWithTransport } from 'codemirror-languageserver';

const ls = languageServerWithTransport({
    transport: myCustomTransport,
    rootUri: 'file:///',
    documentUri: `file:///${filename}`,
    languageId: 'cpp',
});

The Transport interface:

interface Transport {
    send(message: string): void;
    onMessage(callback: (message: string) => void): void;
    onClose(callback: () => void): void;
    onError(callback: (error: Error) => void): void;
    close(): void;
}

You can import Transport and WebSocketTransport from the package.

Document Highlight

Enabled by default. When the cursor is on a symbol, all occurrences in the document are highlighted. Style with CSS:

.cm-lsp-highlight-text,
.cm-lsp-highlight-read { background-color: rgba(255, 255, 0, 0.2); }
.cm-lsp-highlight-write { background-color: rgba(255, 165, 0, 0.3); }

The three classes correspond to DocumentHighlightKind: general text occurrences, read accesses, and write accesses.

Formatting

formatDocument and formatSelection are CodeMirror commands — bind them to keys:

import { keymap } from '@codemirror/view';
import { formatDocument, formatSelection } from 'codemirror-languageserver';

const formattingKeymap = keymap.of([
    { key: 'Shift-Alt-f', run: formatDocument },
    { key: 'Ctrl-k Ctrl-f', run: formatSelection },
]);

Formatting Options

Configure formatting with the formattingOptions facet. By default, tabSize is read from the editor state.

import { formattingOptions } from 'codemirror-languageserver';

// In extensions:
formattingOptions.of({
    tabSize: 2,
    insertSpaces: true,
    trimTrailingWhitespace: true,
    insertFinalNewline: true,
    trimFinalNewlines: true,
})

Rename Symbol

renameSymbol is a CodeMirror command that opens a rename prompt at the top of the editor. If the server supports prepareRename, the current symbol name is used as the placeholder.

import { keymap } from '@codemirror/view';
import { renameSymbol } from 'codemirror-languageserver';

const renameKeymap = keymap.of([
    { key: 'F2', run: renameSymbol },
]);

Style the panel with CSS:

.cm-lsp-rename-panel {
    padding: 4px 8px;
    border-bottom: 1px solid #ddd;
}
.cm-lsp-rename-input {
    font-family: inherit;
    font-size: inherit;
}

Server Capabilities

Use the onCapabilities callback to react when the server finishes initializing — e.g. to show or hide toolbar buttons:

languageServer({
    serverUri: 'ws://localhost:8080',
    rootUri: 'file:///',
    documentUri: `file:///${filename}`,
    languageId: 'cpp',
    onCapabilities(capabilities) {
        // capabilities.documentFormattingProvider
        // capabilities.renameProvider
        // capabilities.completionProvider
        // etc.
        toolbar.update({ capabilities });
    },
})

Initialization Options

The package includes TypeScript definitions for popular language servers:

• PyrightInitializationOptions — Python (Pyright)
• RustAnalyzerInitializationOptions — Rust (rust-analyzer)
• TypeScriptInitializationOptions — TypeScript/JavaScript
• ESLintInitializationOptions — ESLint
• ClangdInitializationOptions — C/C++ (Clangd)
• GoplsInitializationOptions — Go (Gopls)

import { languageServer } from 'codemirror-languageserver';
import type { ClangdInitializationOptions } from 'codemirror-languageserver';

const ls = languageServer<ClangdInitializationOptions>({
    serverUri: 'ws://localhost:8080',
    rootUri: 'file:///',
    documentUri: 'file:///main.cpp',
    languageId: 'cpp',
    initializationOptions: {
        // Type-checked options specific to Clangd
    },
});

Contributing

Contributions are welcome.

Real World Uses

• Toph: Competitive programming platform. Toph uses Language Server Plugin for CodeMirror 6 with its integrated code editor.

License

The library is available under the BSD (3-Clause) License.