# Volarjs

> description: VolarJS has top-notch support for embedded languages and can drastically simplify the mappings needed to get editing features working across the different parts of your files.

---

# Source: https://github.com/volarjs/docs/blob/main/src/content/docs/core-concepts/embedded-languages.mdx

---
title: Embedded languages
description: VolarJS has top-notch support for embedded languages and can drastically simplify the mappings needed to get editing features working across the different parts of your files.
---

A lot of programming languages used these days are composed of other programming languages. The most famous example is HTML, in which you will find JavaScript and CSS in `<script>` and `<style>` blocks respectively. In addition to those, you can even find some inline CSS in the `style` attribute of HTML elements, and some inline JavaScript in the `onclick` (and other events) attribute of HTML elements.

There is actually a remarkable number of examples of this behaviour, especially on the web: The different blocks in [Vue's Single-File Components](https://vuejs.org/guide/scaling-up/sfc.html), the sections in [Svelte's components](https://svelte.dev/docs/svelte-components), the frontmatter syntax and JSX-based component template of [Astro's components](https://docs.astro.build/en/core-concepts/astro-components/), the different blocks in [Markdown](https://spec.commonmark.org/0.29/#fenced-code-blocks) (not to mention the common YAML frontmatter), and the list goes on.

As such, Volar was built on the principle that it is fairly likely that your language will have such embedded languages and has top-notch support for them. Notably, Volar can drastically simplify the mappings needed to get editing features working across the different parts of your files.

**If your language does not have embedded languages: That's completely okay!** Volar will still work for you just as well, and it will be ready if one day you do decide to add embedded languages to your language

---

# Source: https://github.com/volarjs/docs/blob/main/src/content/docs/core-concepts/volar-labs.mdx

---
title: Volar Labs
description: A VS Code extension to help you debug your Volar-powered language server and client.
---

Having a common framework for building editor tooling has many benefits. It allows us to share code, it allows us to share knowledge, and most importantly, it allows us to share the pain of building editor tooling.

Those pesky times where your mappings are off by one, or you're not sure what files are being included in your project, or there's a syntax error in your generated virtual code. We all know those times, and if you don't, you probably will soon.

Volar Labs is a VS Code extension to help you debug your Volar-powered language server and client. **It's the editor tooling for the people who make the editor tooling.**

![A screenshot of Volar Labs, showing the mappings between the different parts of a file being inspected](./volar-labs-1.png)

## Installation

Volar Labs is available on the VS Code Marketplace. You can install it by searching for `volarjs-labs` in the Extensions tab of VS Code, or by [clicking here](https://marketplace.visualstudio.com/items?itemName=johnsoncodehk.volarjs-labs).

## Features

- **List Volar Servers** - See all the Volar servers running in your VS Code instance.
- **Inspect Project** - See the files included in your project.
- **Inspect Virtual File** - See the virtual source code generated by your server.
- **Virtual Source Maps** - See the mappings between the virtual source code and the original source code.
- **TS Memory Usage** - See how much memory TypeScript is using.
- ... and more!

---

# Source: https://github.com/volarjs/docs/blob/main/src/content/docs/core-concepts/why-volar.mdx

---
title: Why Volar?
description: Advantages of using Volar and why you would want to use it.
---

Over the years, programmers have started relying more and more on their code editors to provide them with helpful contextual information and hints about their code. Features such as hover information, diagnostics, and auto-completions are now an absolute norm that users rightfully expect from their editors, no matter what programming languages they are working with.

However, implementing such features is not only a non-trivial task, but it's also understandably rarely the priority of the languages and frameworks authors. And even if you do have the time and resources to implement such features, it's hard to do right, requires a fair amount of domain knowledge, and can be very time consuming to maintain.

**Volar aims to solve this problem by taking care of all the heavy lifting.** Volar provides you all the tools you need to build a great editing experience for your users without having to worry about the nitty-gritty details so you can focus on what matters most to you: Making your language or framework awesome.

---

# Source: https://github.com/volarjs/docs/blob/main/src/content/docs/guides/file-structure.mdx

---
title: "File Structure of a typical Volar project"
description: A guide to understand the file structure of a typical Volar project.
---

This guide will show you how a Volar project is organized and what the different files in your project do.

## Files and directories

Due to needing multiple packages to run the language server and VS Code extension, a Volar project will typically live in a monorepo. This is not a requirement, but it is the most common setup and recommended way to set up a Volar project.

### Server (`packages/language-server`)

All files related to the language server are located in the `packages/language-server` directory.

- `package.json` — Configuration for the language server package, including its dependencies and main entry point.
- `bin/server.js` — The entry point for the language server binary. This file is responsible for starting the language server.
- `src/index.ts` — Main file for the language server, setting up the server and its capabilities.
- `src/language.ts` — Defines the language capabilities and provides methods for handling the project's files.

### Client (`packages/vscode`)

All files related to the VS Code extension are located in the `packages/vscode` directory.

- `package.json` — Configuration for the VS Code extension package, including its dependencies, main entry point, and activation events.
- `src/extension.ts` — Main file for the VS Code extension, setting up the client and activating features.
- `scripts/build.js` — Script for building the VS Code extension.

## Full example

Your Volar project will, in most cases, look similar to the following:

---

# Source: https://github.com/volarjs/docs/blob/main/src/content/docs/guides/first-server.mdx

---
title: Your First Volar Language Server
description: A simple guide to creating your first Volar language server.
---

> This page is a work in progress. Interested in contributing some documentation to it, or want to improve it? [Edit this page on GitHub](https://github.com/volarjs/docs/blob/main/src/content/docs/guides/first-server.mdx)


In this guide, you will learn create a simple Volar language server and VS Code client. To keep things simple, the language it'll support will look suspiciously like HTML, albeit with one twist: Only one `<style>` tag will be allowed. The language will be called HTML1.

This guide assumes that you have a basic understanding of TypeScript and Node.js, and also of what a language server is. If you're not familiar with language servers, you might want to read the "What is the Language Server Protocol?" section of the [Language Server Protocol](https://microsoft.github.io/language-server-protocol/) homepage before continuing.

> 💡 Interested in seeing the final product? Check out the [starter project](https://github.com/volarjs/starter) on GitHub.

## Prerequisites

- [Visual Studio Code](https://code.visualstudio.com/) version 1.55 or higher.
- [Node.js](https://nodejs.org/en/) version 14 or higher.
- Basic knowledge of JavaScript and Node.
- (Optional) Install the [Volar Labs](https://volarjs.dev/core-concepts/volar-labs/) extension for VS Code.

## Getting Started

First create a new project directory and initialize a new Node.js project:

---

# Source: https://github.com/volarjs/docs/blob/main/src/content/docs/index.mdx

---
title: Volar
description: VolarJS is a modern embedded language tooling framework that aims to simplify the development of language support for editors. 
template: splash
hero:
  tagline: The Embedded Language Tooling Framework.
  image:
    file: ../../assets/logo.svg
  actions:
    - text: Why Volar?
      link: /core-concepts/why-volar
      icon: right-arrow
      variant: primary
    - text: Starter project
      link: https://github.com/volarjs/starter
      icon: right-arrow
      variant: secondary
    - text: View on GitHub
      link: https://github.com/volarjs
      icon: external
      variant: minimal
---



## Sponsors

---

# Source: https://github.com/volarjs/docs/blob/main/src/content/docs/reference/languages.mdx

---
title: Languages
---

> This page is a work in progress. Interested in contributing some documentation to it, or want to improve it? [Edit this page on GitHub](https://github.com/volarjs/docs/blob/main/src/content/docs/reference/languages.mdx)

As can be expected from a framework for language servers, Volar allows you to define the languages you want to support in your project.

## Shape of a language definition

A language definition is a JavaScript object that contains a `createVirtualCode` and a `updateVirtualCode` function.

```ts title="src/my-language.ts"
export const language = {
	createVirtualCode(fileId, languageId, snapshot) {
		// Create a virtual code object
	},
	updateVirtualCode(_fileId, languageCode, snapshot) {
		// Update the virtual code object
	},
};
```

As the names suggests, those methods create and update a `VirtualCode`. A `VirtualCode` object is created for each file that your language server will handle. These can then be accessed in the hooks of the [services](/reference/services) that provides the features of your language server, as such they're also a place you can store additional information about the file that could be useful to know for the features of your services.

Albeit not required, a common pattern is to define a JavaScript class that implements the `VirtualCode` interface, as this makes it easier to later add more properties and methods to the virtual code object and unlock the ability to use `instanceof` to check if a virtual code object is of a certain type.

```ts title="src/my-language.ts"

export const language = {
	createVirtualCode(fileId, languageId, snapshot) {
		if (languageId !== 'my-language')
			return;

		return new MyLanguageVirtualCode(snapshot);
	},
	updateVirtualCode(_fileId, languageCode, snapshot) {
		languageCode.update(snapshot);
		return languageCode;
	},
} satisfies LanguagePlugin<MyLanguageVirtualCode>;

export class MyLanguageVirtualCode implements VirtualCode {
	id = 'root';
	languageId = 'my-language';
	mappings = []

	constructor(
		public snapshot: ts.IScriptSnapshot
	) {
		this.onSnapshotUpdated();
	}

	public update(newSnapshot: ts.IScriptSnapshot) {
		this.snapshot = newSnapshot;
		this.onSnapshotUpdated();
	}

	onSnapshotUpdated() {
		// Update the virtual code object
	}
}
```

This is a simple example of a language definition, where `MyVirtualLanguageCode` only does the strict minimum possible. In a real language definition, you would most likely have a lot more properties and methods available on the `MyLanguageVirtualCode` class.

### Embedded languages

If your language supports [embedded languages](/core-concepts/embedded-languages/), your instance `VirtualCode` should include a `embeddedCodes` property that contains an array of `VirtualCode` instances for the embedded languages.

```ts title="src/my-language.ts" ins={20, 34-52} collapse={1-14, 22-31}

export const language = {
	createVirtualCode(fileId, languageId, snapshot) {
		if (languageId !== 'my-language')
			return;

		return new MyLanguageVirtualCode(snapshot);
	},
	updateVirtualCode(_fileId, languageCode, snapshot) {
		languageCode.update(snapshot);
		return languageCode;
	},
} satisfies LanguagePlugin<MyLanguageVirtualCode>;

export class MyLanguageVirtualCode implements VirtualCode {
	id = 'root';
	languageId = 'my-language';
	mappings = []
	embeddedCodes: VirtualCode[] = []

	constructor(
		public snapshot: ts.IScriptSnapshot
	) {
		this.onSnapshotUpdated();
	}

	public update(newSnapshot: ts.IScriptSnapshot) {
		this.snapshot = newSnapshot;
		this.onSnapshotUpdated();
	}

	onSnapshotUpdated() {
		const snapshotContent = this.snapshot.getText(0, this.snapshot.getLength());

		// Find embedded languages
		const embeddedLanguages = findEmbeddedLanguages(snapshotContent);

		// Create virtual code objects for embedded languages
		this.embeddedCodes = embeddedLanguages.map(embeddedLanguage => {
			return {
				id: embeddedLanguage.id,
				languageId: embeddedLanguage.languageId,
				mappings: [],
				snapshot: {
						getText: (start, end) => embeddedLanguage.content.substring(start, end),
						getLength: () => embeddedLanguage.content.length,
						getChangeRange: () => undefined,
					}
			}
		});
	}
}
```

---

# Source: https://github.com/volarjs/docs/blob/main/src/content/docs/reference/services.mdx

---
title: Services
description: A list of available services in VolarJS and how to use them.
---

Services are the building blocks of Volar language servers. They are responsible for providing all the features you'd expect in a language server, completions, diagnostics, hover information, you name it.

While services are technically not tied to individual languages, they are often designed to work with a specific language or file type, including [embedded languages](/core-concepts/embedded-languages).

For example, if you were to implement a Volar language server for HTML, you would likely end up with three different services, one for general HTML support, one for CSS support and one for JavaScript support, the latter two being used for `<style>` and `<script>` tags respectively.

## Shape of a service

A service is a JavaScript object, whose only required property is a `create` method. The `create` method is called when the service is initialized, and it should return an object with methods that implement the various features of the service.

These methods are called by the Volar language server when it needs to perform a specific task, such as providing completions or diagnostics. Those methods map almost exactly to the [Language Server Protocol](https://microsoft.github.io/language-server-protocol/) (LSP) requests, for instance `textDocument/completion` becomes `provideCompletionItems`, `textDocument/hover` becomes `provideHover`, etc.

```ts title="service.ts"
export const service = {
	name: 'my-service', // The name of the service, this is used to identify the service in the logs and in Volar Labs
	create(context): ServicePluginInstance {
		return {
			provideHover(document, position, token) {
				// Implement hover support here
			},
			// More methods...
		};
	},
} satisfies ServicePlugin;
```

## Using a service

When initializing the language server, the list of services to use is passed as an option to the `initialize` method.

```ts title="server.ts"
  createConnection,
  createServer,
  createSimpleProjectProviderFactory,
} from "@volar/language-server/node";

const connection = createConnection();
const server = createServer(connection);

connection.listen();

connection.onInitialize((params) => {
  return server.initialize(params, createSimpleProjectProviderFactory(), {
    // ...
    getServicePlugins() {
      return [service];
    },
  });
});

connection.onInitialized(() => {
  server.initialized();
});
```

## First-party services

The Volar team maintains a number of first-party services that are ready for use in your Volar language servers. These services should cover the vast majority of common use cases, such as providing completions, diagnostics, hover information, etc for HTML, CSS, JSON, JavaScript and more, or integrating with well-known tools like Emmett, Prettier, etc.

To see a list of all first-party services, see the [volarjs/services](https://github.com/volarjs/services) repository.

## Methods

### `provideCompletionItems`

**Signature:** `(document: TextDocument, position: Position, token: CancellationToken) => CompletionItem[] | Promise<CompletionItem[]>`

This method is called when the user requests completions at a specific position in the document.

```ts title="service.ts"

export const service = {
	name: 'my-service',
	create(context): ServicePluginInstance {
		return {
			provideCompletionItems(document, position, token) {
				return {
					isIncomplete: true,
					items: [
						{
							label: 'Hello',
							kind: CompletionItemKind.Text,
							isIncomplete: false
						},
						{
							label: 'World',
							kind: CompletionItemKind.Text,
							isIncomplete: false
						},
					]
				}
			},
		};
	},
} satisfies ServicePlugin;
```

### `resolveCompletionItem`

**Signature:** `(item: CompletionItem, token: CancellationToken) => CompletionItem | Promise<CompletionItem>`

This method is called when the user selects a completion item from the list of completions. It allows you to provide additional information for the selected completion item. This is often used when calculating the full information for completions is expensive and you want to defer it until the user actually selects a specific completion.

### `provideCodeActions`

**Signature:** `(document: TextDocument, range: Range, context: CodeActionContext, token: CancellationToken) => CodeAction[] | Promise<CodeAction[]>`

This method is called when the user requests code actions for a specific range in the document. Code actions are typically used to fix issues or improve the code (e.g. "Extract Method", "Add missing import").

### `resolveCodeAction`

**Signature:** `(action: CodeAction, token: CancellationToken) => CodeAction | Promise<CodeAction>`

This method is called when the user selects a code action from the list of code actions. It allows you to provide additional information for the selected code action.

### `provideHover`

**Signature:** `(document: TextDocument, position: Position, token: CancellationToken) => Hover | Promise<Hover>`

This method is called when the user requests hover information at a specific position in the document.

### `provideSignatureHelp`

**Signature:** `(document: TextDocument, position: Position, token: CancellationToken) => SignatureHelp | Promise<SignatureHelp>`

This method is called when the user requests signature help at a specific position in the document.

### `provideDefinition`

**Signature:** `(document: TextDocument, position: Position, token: CancellationToken) => Location | Location[] | Promise<Location | Location[]>`

This method is called when the user requests the definition of a symbol at a specific position in the document. This method powers features like "Go to Definition".

### `provideReferences`

**Signature:** `(document: TextDocument, position: Position, context: ReferenceContext, token: CancellationToken) => Location[] | Promise<Location[]>`

This method is called when the user requests references to a symbol at a specific position in the document. This method powers features like "Find All References".

### `provideDocumentHighlights`

**Signature:** `(document: TextDocument, position: Position, token: CancellationToken) => DocumentHighlight[] | Promise<DocumentHighlight[]>`

This method is called when the user requests highlights for a symbol at a specific position in the document.

### `provideDocumentSymbols`

**Signature:** `(document: TextDocument, token: CancellationToken) => SymbolInformation[] | Promise<SymbolInformation[]>`

This method is called when the user requests symbols in the document.


### `provideCodeLens`

**Signature:** `(document: TextDocument, token: CancellationToken) => CodeLens[] | Promise<CodeLens[]>`

This method is called when the user requests code lenses in the document.

### `resolveCodeLens`

**Signature:** `(codeLens: CodeLens, token: CancellationToken) => CodeLens | Promise<CodeLens>`

This method is called when the user selects a code lens from the list of code lenses. It allows you to provide additional information for the selected code lens.

### `provideDocumentFormattingEdits`

**Signature:** `(document: TextDocument, options: FormattingOptions, token: CancellationToken) => TextEdit[] | Promise<TextEdit[]>`

This method is called when the user requests formatting for the entire document.

### `provideDocumentRangeFormattingEdits`

**Signature:** `(document: TextDocument, range: Range, options: FormattingOptions, token: CancellationToken) => TextEdit[] | Promise<TextEdit[]>`

This method is called when the user requests formatting for a specific range in the document.

### `provideOnTypeFormattingEdits`

**Signature:** `(document: TextDocument, position: Position, ch: string, options: FormattingOptions, token: CancellationToken) => TextEdit[] | Promise<TextEdit[]>`

This method is called when the user types a specific character in the document.

### `provideRenameEdits`

**Signature:** `(document: TextDocument, position: Position, newName: string, token: CancellationToken) => WorkspaceEdit | Promise<WorkspaceEdit>`

This method is called when the user requests to rename a symbol at a specific position in the document.

### `provideDocumentLinks`

**Signature:** `(document: TextDocument, token: CancellationToken) => DocumentLink[] | Promise<DocumentLink[]>`

This method is called when the user requests links in the document.

### `resolveDocumentLink`

**Signature:** `(link: DocumentLink, token: CancellationToken) => DocumentLink | Promise<DocumentLink>`

This method is called when the user selects a link from the list of links. It allows you to provide additional information for the selected link.

### `provideDocumentColors`

**Signature:** `(document: TextDocument, token: CancellationToken) => ColorInformation[] | Promise<ColorInformation[]>`

This method is called when the user requests colors in the document.

### `provideColorPresentations`

**Signature:** `(color: Color, document: TextDocument, range: Range, token: CancellationToken) => ColorPresentation[] | Promise<ColorPresentation[]>`

This method is called when the user selects a color from the list of colors. It allows you to provide additional information for the selected color.

### `provideFoldingRanges`

**Signature:** `(document: TextDocument, context: FoldingContext, token: CancellationToken) => FoldingRange[] | Promise<FoldingRange[]>`

This method is called when the user requests folding ranges in the document.

### `provideSelectionRanges`

**Signature:** `(document: TextDocument, positions: Position[], token: CancellationToken) => SelectionRange[] | Promise<SelectionRange[]>`

This method is called when the user requests selection ranges at specific positions in the document.

### `provideDocumentSemanticTokens`

**Signature:** `(document: TextDocument, token: CancellationToken) => SemanticTokens | Promise<SemanticTokens>`

This method is called when the user requests semantic tokens in the document.

### `provideDocumentSemanticTokensEdits`

**Signature:** `(document: TextDocument, previousResultId: string, token: CancellationToken) => SemanticTokens | SemanticTokensEdits | Promise<SemanticTokens | SemanticTokensEdits>`

This method is called when the user requests semantic tokens edits in the document.

### `provideLinkedEditingRanges`

**Signature:** `(document: TextDocument, position: Position, token: CancellationToken) => LinkedEditingRanges | Promise<LinkedEditingRanges>`

This method is called when the user requests linked editing ranges at a specific position in the document.

### `provideCallHierarchyItems`

**Signature:** `(document: TextDocument, position: Position, token: CancellationToken) => CallHierarchyItem[] | Promise<CallHierarchyItem[]>`

This method is called when the user requests call hierarchy items for a symbol at a specific position in the document.

### `provideCallHierarchyIncomingCalls`

**Signature:** `(document: TextDocument, position: Position, token: CancellationToken) => CallHierarchyIncomingCall[] | Promise<CallHierarchyIncomingCall[]>`

This method is called when the user requests incoming calls for a symbol at a specific position in the document.

### `provideCallHierarchyOutgoingCalls`

**Signature:** `(document: TextDocument, position: Position, token: CancellationToken) => CallHierarchyOutgoingCall[] | Promise<CallHierarchyOutgoingCall[]>`

This method is called when the user requests outgoing calls for a symbol at a specific position in the document.

### `provideInlayHints`

**Signature:** `(document: TextDocument, token: CancellationToken) => InlayHint[] | Promise<InlayHint[]>`

This method is called when the user requests inlay hints in the document.

### `resolveInlayHint`

**Signature:** `(hint: InlayHint, token: CancellationToken) => InlayHint | Promise<InlayHint>`

This method is called when the user selects an inlay hint from the list of inlay hints. It allows you to provide additional information for the selected inlay hint.