Home

Awesome

@codingame/monaco-vscode-api · monthly downloads npm version PRs welcome

This NPM module allows to integrate full VSCode functionality into your monaco-editor.

For more information, please checkout the project's wiki.

Installation

npm install vscode@npm:@codingame/monaco-vscode-api
npm install monaco-editor@npm:@codingame/monaco-vscode-editor-api
npm install -D @types/vscode

@codingame/monaco-vscode-api is installed as an alias to vscode to be able to run import * as vscode from 'vscode', similar to what is done inside a VSCode extension

@codingame/monaco-vscode-editor-api is installed as an alias to monaco-editor because it provides the same api as the official monaco-editor

Usage

If you are just starting with monaco-editor and monaco-vscode-api you may find helpful the Getting Started Guide in the wiki.

Monaco service override

Most of VSCode functionality implemented as "services", e.g.

By default, Monaco uses a simplified versions of the VSCode services, called standalone services. This package allows to

  1. override them with fully-functional alternatives from VSCode
  2. add new services that were not included in Monaco

Here is an example usage that overrides Monaco default configuration with VSCode json-based settings:

// default monaco-editor imports
import * as monaco from 'monaco-editor';
import editorWorker from 'monaco-editor/esm/vs/editor/editor.worker?worker';

// utilities to override Monaco services
import { initialize } from 'vscode/services'
import getConfigurationServiceOverride, { updateUserConfiguration } from '@codingame/monaco-vscode-configuration-service-override'

window.MonacoEnvironment = {
  getWorker: (_moduleId, _label) => new editorWorker()
}

// overriding Monaco service with VSCode
await initialize({
    ...getConfigurationServiceOverride(),
});

// json config like in vscode settings.json
updateUserConfiguration(`{
    "editor.fontSize": 30,
    "editor.lineHeight": 30,
    "editor.fontFamily": "monospace",
    "editor.fontWeight": "bold",
    "editor.letterSpacing": 0,
}`)

// creating an editor with VSCode configuration
monaco.editor.create(document.getElementById('editor')!, {
    value: "Editor with VSCode config and large bold fonts",
});

[!NOTE] initialize can only be called once (and it should be called BEFORE creating your first editor).

Each get<service-name>ServiceOverride contains the service and some glue to make VSCode service work with Monaco.

List of service overrides

Some basic service overrides are coming with this package as dependencies:

However, most of the services are separated into different modules, so they can be imported as required. You can find a full list of services in the corresponding wiki page.

Default vscode extensions

VSCode uses a bunch of default extensions. Most of them are used to load the default languages and grammars (see https://github.com/microsoft/vscode/tree/main/extensions).

This library bundles and publishes them as separate packages, which allows to use the ones you want. To use an extension, just install the corresponding package and import it in the beginning of the file:

import '@codingame/monaco-vscode-javascript-default-extension'
import '@codingame/monaco-vscode-json-default-extension'
...

Here is an example of usage of default VSCode theme extension with theme service override:

// importing default VSCode theme extension
import "@codingame/monaco-vscode-theme-defaults-default-extension";	

// default monaco-editor imports
import * as monaco from 'monaco-editor';
import editorWorker from 'monaco-editor/esm/vs/editor/editor.worker?worker';

// utilities to override Monaco services
import { initialize } from 'vscode/services'
import getThemeServiceOverride from "@codingame/monaco-vscode-theme-service-override";

window.MonacoEnvironment = {
  getWorker: function (_moduleId, _label) {
	return new editorWorker();
  }
}

// overriding Monaco service with VSCode
await initialize({
    ...getThemeServiceOverride(),
});

// creating an editor with VSCode theme
monaco.editor.create(document.getElementById('editor')!, {
    value: "Editor with VSCode Theme Support",
});

See the full list of ported default extensions

Loading vsix file

VSCode extensions are bundled as vsix files. This library publishes a rollup plugin (vite-compatible) that allows to load a vsix file.

import vsixPlugin from '@codingame/monaco-vscode-rollup-vsix-plugin'
...
plugins: [
  ...,
  vsixPlugin()
]

import './extension.vsix'

Localization

This library also offers the possibility to localize vscode and the extensions in the supported languages. To do so, import one of the following packages before anything else:

⚠️ The language pack should be imported and loaded BEFORE anything else from this library is loaded. Otherwise, some translations would be missing and an error would be displayed in the console. ⚠️

Model creation

The official monaco-editor package provides a function to create models: monaco.editor.createModel.

This method creates a standalone model that cannot be found or used by any VSCode services.

The recommended way is to used the createModelReference method instead (added on top of the official monaco-editor api) which returns instead a reference to a model.

It has some pros:

To work, it needs the file to exist on the virtual filesystem. It can be achieved either by:

before:

import * as monaco from 'monaco-editor'
const model = monaco.editor.createModel(...)
const editor = monaco.editor.create({ model, ... })

...

model.dispose()
editor.dispose()

after:

import * as monaco from 'monaco-editor'
import { RegisteredFileSystemProvider, RegisteredMemoryFile, registerFileSystemOverlay } from '@codingame/monaco-vscode-files-service-override'

const fileUri = monaco.Uri.file(<file uri>);

const fileSystemProvider = new RegisteredFileSystemProvider(false)
fileSystemProvider.registerFile(new RegisteredMemoryFile(fileUri, <file content>))
const overlayDisposable = registerFileSystemOverlay(1, fileSystemProvider)

const modelRef = await monaco.editor.createModelReference(fileUri)

const editor = monaco.editor.create({ model: modelRef.object.textEditorModel })

...

await modelRef.object.save()

...

modelRef.dispose()
editor.dispose()
overlayDisposable.dispose()

createModelReference return a reference to a model. The value is fetched from the memory filesystem. The reference can then be disposed, the model will only be disposed if there is no remaining references.

VSCode api usage

To be able to use the VSCode api directly from your code, you need to import vscode/localExtensionHost and wait for the services to be initialized.

You will then be able to import it as if you were in a VSCode extension:

import * as vscode from 'vscode'
import 'vscode/localExtensionHost'

const range = new vscode.Range(...)
vscode.languages.registerCompletionItemProvider(...)

You can also register a new extension from its manifest:

import { registerExtension, initialize, ExtensionHostKind } from 'vscode/extensions'

await initialize()

const { registerFileUrl, getApi } = registerExtension({
  name: 'my-extension',
  publisher: 'someone',
  version: '1.0.0',
  engines: {
      vscode: '*'
  },
  contributes: {
  }
}, ExtensionHostKind.LocalProcess)

registerFileUrl('/file-extension-path.json', new URL('./file-real-path.json', import.meta.url).toString())

const vscode = await getApi()

vscode.languages.registerCompletionItemProvider(...)

Demo

Try it out on https://monaco-vscode-api.netlify.app/

There is a demo that showcases the service-override features. It includes:

From CLI run:

# build monaco-vscode-api (the demo use it as a local dependency)
npm ci
npm run build
# start demo
cd demo
npm ci
npm start
# OR: for vite debug output
npm run start:debug

For the debug feature, also run:

npm run start:debugServer

⚠️ Building monaco-vscode-api is only supported on Linux or Mac. It you use Windows, have a look at WSL ⚠️

Remote agent

See the VSCode Server wiki page.

Troubleshooting

If something doesn't work, make sure to check out the Troubleshooting wiki page.

History

This project was mainly created to make the implementation of monaco-languageclient more robust and maintainable.

monaco-languageclient uses vscode-languageclient which was built to run inside a VSCode extension. VSCode extensions communicate with the editor via an API they can import into their code.

The VSCode api exports:

The first implementations of monaco-languageclient were using a fake VSCode api implementation. The vscode-languageclient was hacked so the VSCode<->protocol object converters were mainly bypassed, so the fake VSCode api was receiving Language Server Protocol objects. Then the objects were transformed using custom transformers into Monaco objects to communicate with the monaco api.

This approach has some disadvantages:

With this library, it would be possible to plug vscode-languageclient directly on top of monaco, monaco-languageclient still helps to do so by: