Guides

June 26, 2026 ยท View on GitHub

This section covers the general concepts and usage patterns for the Monaco Language Client. These guides are designed to get you up and running quickly.

Section Contents

  • Getting Started - Your first Monaco Language Client integration with a minimal working example
  • Configuration - Understanding configuration options and how to customize your setup
  • Examples - Simple, practical examples demonstrating common integration patterns
  • Langium Integration Guides - Guides for integrating & interacting with language servers from Langium-based DSLs
  • Troubleshooting - Common issues and how to resolve them

Quick Overview

monaco-languageclient provides two different integration approaches for monaco-editor. Theses are the classic mode and the extended mode. The former allows to use monaco-editor with monarch and its internal languages api. The latter automatically makes use of Textmate for theming and allows to configure all possible services from @codingame/monaco-vscode-api.

We recommend to use extended mode allowing to make use of VSCode services for richer functionality. Compared with the classic mode the only difference regarding the monaco-vscode-api configuration object is the $type property. We put this to use below.

import type { MonacoVscodeApiConfig } from 'monaco-languageclient/vscodeApiWrapper';

const vscodeApiConfig: MonacoVscodeApiConfig = {
  // both $type and viewsConfig are mandatory
  $type: 'extended',
  viewsConfig: {
    $type: 'ViewsService'
  }
  // further configuration
};

Classic Mode

Light-weight integration with standalone Monaco Editor.

import type { MonacoVscodeApiConfig } from 'monaco-languageclient/vscodeApiWrapper';

const vscodeApiConfig: MonacoVscodeApiConfig = {
  // both $type and viewsConfig are mandatory
  $type: 'classic',
  viewsConfig: {
    // in classic mode only one type can be configured
    $type: 'EditorService'
  }
  // further configuration
};

Editor start

The vscodeApiConfig created in any of the two examples above is used to initialize the VSCode api and all services. The MonacoVscodeApiWrapper can only be started once, and it has to be done before starting the editor. Errors will be thrown if you don't do that first.

import { MonacoVscodeApiWrapper } from 'monaco-languageclient/vscodeApiWrapper';
import { EditorApp } from 'monaco-languageclient/editorApp';

// always start the monaco-vscode-api wrapper first and await it
const apiWrapper = new MonacoVscodeApiWrapper(vscodeApiConfig);
await apiWrapper.start();

// create editor with empty content
const editorApp = new EditorApp({});
const htmlContainer = document.getElementById('monaco-editor-root')!;
await editorApp.start(htmlContainer);

Generally you should start with Extended Mode unless you have specific constraints that require Classic Mode.

Next Steps