Volar.js Documentation

To use Volar features in Monaco, you must implement a Web Worker that initializes a language service. You can use createSimpleWorkerLanguageService for general purposes or createTypeScriptWorkerLanguageService for TypeScript-specific support.

Basic Worker Setup

Use createSimpleWorkerLanguageService to initialize the worker context and environment.

TypeScript Support

To add TypeScript support, use createTypeScriptWorkerLanguageService. You must provide the typescript instance, compilerOptions, and a uriConverter to map between file names and vscode-uri objects. You should also include the volar-service-typescript plugin.

Adding ATA (Automatic Type Acquisition) Support

To enable automatic fetching of type definitions from npm, set the env.fs property using createNpmFileSystem() from @volar/jsdelivr within your worker initialization.

// my-lang.worker.ts
import * as worker from 'monaco-editor-core/esm/vs/editor/editor.worker';
import type * as monaco from 'monaco-editor-core';
import type { LanguageServiceEnvironment } from '@volar/language-service';
import { createSimpleWorkerLanguageService } from '@volar/monaco/worker';
import { URI } from 'vscode-uri';

self.onmessage = () => {
	worker.initialize((ctx: monaco.worker.IWorkerContext) => {
		const env: LanguageServiceEnvironment = {
			workspaceFolders: [
				URI.parse('file:///'),
			],
		};
		return createSimpleWorkerLanguageService({
			workerContext: ctx,
			env,
			languagePlugins: [],
			languageServicePlugins: [],
		});
	});
};

Once the worker is configured, use the @volar/monaco utility functions to activate core language features. You must first register the language in Monaco, then create a WebWorker instance, and finally call the activation functions.

Key functions:

• activateMarkers: Enables diagnostic markers (errors, warnings, etc.).
• activateAutoInsertion: Enables automatic tag closing/insertion.
• registerProviders: Registers IntelliSense/completion providers.

All these functions require a sync files callback that returns an array of Uri objects representing the current files in the editor context.

import type { WorkerLanguageService } from '@volar/monaco/worker';
import { editor, languages, Uri } from 'monaco-editor-core';
import { activateMarkers, activateAutoInsertion, registerProviders } from '@volar/monaco';

languages.register({ id: 'my-lang', extensions: ['.my-lang'] });

languages.onLanguage('my-lang', () => {
	const worker = editor.createWebWorker<WorkerLanguageService>({
		moduleId: 'vs/language/my-lang/myLangWorker',
		label: 'my-lang',
	});
	activateMarkers(
		worker,
		['my-lang'],
		'my-lang-markers-owner',
		// sync files
		() => [Uri.file('/Foo.my-lang'), Uri.file('/Bar.my-lang')],
		editor
	);
	// auto close tags
	activateAutoInsertion(
		worker,
		['my-lang'],
		// sync files
		() => [Uri.file('/Foo.my-lang'), Uri.file('/Bar.my-lang')],
		editor
	);
	registerProviders(
		worker,
		['my-lang'],
		// sync files
		() => [Uri.file('/Foo.my-lang'), Uri.file('/Bar.my-lang')],
		languages
	)
});

The CodeInformation interface is attached to CodeMappings to control which language features (like diagnostics or autocomplete) are active in specific regions of generated (virtual) code. This allows you to enable features in some parts of a generated file while disabling them in others.

Available configuration properties:

• verification: Controls diagnostics (syntactic/semantic) and code actions. Can be a boolean or an object with a shouldReport(source, code) callback to decide if a diagnostic should propagate back to the original source.
• completion: Controls assisted completion. Can be a boolean or an object with isAdditional and onlyImport flags.
• semantic: Controls hover, inlay hints, code lens, and semantic tokens. Can be a boolean or an object with a shouldHighlight() callback.
• navigation: Controls reference relationships, renaming, and symbol resolution. Can be a boolean or an object with shouldHighlight(), shouldRename(), resolveRenameNewName(newName), and resolveRenameEditText(newText).
• structure: A boolean indicating if the code correctly reflects structural information.
• format: A boolean indicating if the code correctly reflects formatting information.

export interface CodeInformation {
	verification?: boolean | {
		shouldReport?(source: string | undefined, code: string | number | undefined): boolean;
	};
	completion?: boolean | {
		isAdditional?: boolean;
		onlyImport?: boolean;
	};
	semantic?: boolean | {
		shouldHighlight?(): boolean;
	};
	navigation?: boolean | {
		shouldHighlight?(): boolean;
		shouldRename?(): boolean;
		resolveRenameNewName?(newName: string): string;
		resolveRenameEditText?(newText: string): string;
	};
	structure?: boolean;
	format?: boolean;
}

The createLanguageServiceHost function creates a specialized ts.LanguageServiceHost that handles several complex integration tasks:

1. Plugin Extensions: It automatically detects and includes extra file extensions defined by Volar plugins (e.g., .vue, .svelte) in the readDirectory and getCompilationSettings calls. It sets allowNonTsExtensions to true automatically.
2. Virtual Files & Generated Scripts: It manages the lifecycle of virtual files. If a Volar script is generated, the host can retrieve serviceScripts and extraServiceScripts provided by the language plugin, making them visible to the TypeScript compiler.
3. Module Resolution: It enhances module resolution by using a ModuleResolutionCache and a custom resolveModuleName function that accounts for Volar's plugin-driven file resolution.
4. Automatic Synchronization: The host implements a sync() mechanism that checks the projectHost.getProjectVersion() against the last known version. If the project has changed, it refreshes the file registry, virtual snapshots, and script versions to ensure the TypeScript service is working with up-to-date data.