volar-docs/docs/getting-started.md

# VolarJS Getting Started

> [Docs Index](README.md) • [Repo README](../README.md) • [Plugin Authoring](plugin-authoring.md) • [Source Map & Code Gen](source-map-and-code-gen.md) • [Configuration & Projects](configuration-and-projects.md)

VolarJS is the reference implementation of Vue Language Server tooling. Its packages are intentionally small so you can wire only what you need—whether that is a full LSP server, a web-based editor integration, or a bespoke CLI that runs Vue-aware transforms. This guide explains the moving pieces, how they relate, and the quickest path to seeing language features light up.

## Mental Model

```
Vue source files ──▶ @volar/language-core ──▶ @volar/language-service plugins ──▶ Host adapters (LSP, VS Code, Monaco, custom)
```

1. **File understanding** happens in `@volar/language-core`. It parses Vue SFCs, tracks virtual files, and creates source maps between template/script/style sections.
2. **Language features** live in `@volar/language-service` (hover, completion, diagnostics, etc.) and are provided by plugins. Vue’s default feature set is one plugin; you can add more.
3. **Adapters** such as `@volar/language-server` or `@volar/monaco` connect the language service to an IDE, editor, or any host that speaks a protocol.

## Package Overview

### Core Building Blocks

| Package | What it does | When to depend on it |
| --- | --- | --- |
| `@volar/source-map` | Bidirectional source-map abstraction used everywhere Volar needs to point back into the user’s Vue/TS files. Supports stacked maps (template <-> TS <-> emitted JS). | Useful whenever you create custom virtual files or remap diagnostics. |
| `@volar/code-gen` | Utility for generating virtual TypeScript text plus accompanying source maps in lockstep. The Vue plugin uses it to describe script/template output. | Authoring custom language-core plugins or transforms. |
| `@volar/language-core` | Creates the document graph, manages embedded files, and wires `source-map` + `code-gen` so features understand Vue SFC structure. | Always required; everything else builds on the core. |
| `@volar/typescript` | Wraps the TS compiler API, exposing helpers to build/refresh programs, track script snapshots, and share language service hosts. | Needed whenever you want TS-powered diagnostics or IntelliSense (nearly all workflows). |

### Service Layer

| Package | What it does | When to depend on it |
| --- | --- | --- |
| `@volar/language-service` | Orchestrates feature plugins (hover, completion, code actions, etc.) and exposes the API a host will call. | Required for any integration responding to language requests. |
| `@volar/vue-language-core` | Vue-specific implementation of language-core plugins (parses `.vue` blocks, tracks template regions, emits TS code). | Needed if you want first-party Vue behavior without reinventing parsing. |
| `@volar/vue-language-service` | Bundled set of language-service plugins delivering Vue-aware completions, diagnostics, refactors, formatting, etc. | Drop-in when you just need the standard Vue feature set. |
| `@volar/vue-typescript` | Provides a TypeScript plugin so TS itself understands `.vue` files (Take Over Mode, `vue-tsc`). | Required if you let TypeScript drive the project graph or run `vue-tsc`. |
| `volar-service-*` plugins | Feature add-ons (Prettier formatting, CSS frameworks, component libraries). Each exposes hooks for both core and language-service layers. | Opt-in when the default Vue plugin is not enough. |

#### Common `volar-service-*` Add-ons

| Plugin | Capability | Notes |
| --- | --- | --- |
| `volar-service-prettier` | Formatting for templates + scripts via Prettier. | Configure formatter options via `initializationOptions.plugins.prettier`. |
| `volar-service-css` | CSS/SCSS completions, diagnostics, folding. | Injects style virtual documents; customizable with `css.languages`. |
| `volar-service-html` | HTML attribute hints, tag completions for template sections. | Useful for custom component libs that mirror HTML behavior. |
| `volar-service-typescript-twoslash-queries` | Inline `// ^?` query evaluation for debugging type state. | Great for docs/playground experiences. |
| `volar-service-emmet` | Emmet abbreviations inside Vue templates. | Enable selectively per workspace to avoid conflicts. |

All services share the same `LanguageServicePlugin` interface, so you can inspect these packages as reference implementations when building your own feature modules.

### Adapter / Host Packages

| Package | What it does | When to depend on it |
| --- | --- | --- |
| `@volar/language-server` | Wraps the language service with an LSP transport (3.17), file watching, and JSON-RPC plumbing. | Editors that speak LSP (VS Code, Neovim, Sublime LSP, etc.). |
| `@volar/kit` | Convenience bootstrapper for CLIs and custom hosts; bundles configs, file watching, and plugin wiring helpers. | Rapidly wiring a bespoke integration or experimentation harness. |
| `@volar/editor` | Provides thin abstractions around text documents, connections, and workspace edits so non-LSP hosts can embed Volar with less boilerplate. | Custom IDEs or web editors that do not rely on Monaco. |
| `@volar/monaco` | Binds the language service to Monaco Editor APIs (workers, markers, completion providers). | Browser-based playgrounds, docs sandboxes, or VS Code Web-style apps. |

> Tip: “VolarJS” refers to the overall toolkit. Individual packages keep the `@volar/` scope, core/service helpers focus on composition, and feature plugins often start with `volar-service-`.

## Installation Cheatsheet

```bash
npm install --save-dev @volar/language-core @volar/language-service @volar/typescript
```

Add the adapter you need:

- LSP host: `npm install --save-dev @volar/language-server`
- Web editor: `npm install --save @volar/monaco`
- Extra features: `npm install --save-dev volar-service-<name>`

## Bootstrapping the Core + Service

```ts
// tooling/createVolarService.ts
import { createLanguageCore } from '@volar/language-core';
import { createLanguageService } from '@volar/language-service';
import { createTypeScriptProject } from '@volar/typescript';
import vuePlugin from '@volar/vue-language-service'; // ships inside the main repo

export function createVolarService(tsconfigPath: string) {
  const tsProject = createTypeScriptProject(tsconfigPath);
  const core = createLanguageCore({
    plugins: [vuePlugin.tsPlugin],
    ts: tsProject.typescript,
    getScriptContent: tsProject.host.readFile,
  });

  return createLanguageService(core, {
    plugins: [vuePlugin.languageService],
  });
}
```

- **Core setup** wires TypeScript and Vue-specific transforms.
- **Language service** registers plugins. Each plugin may expose both a TypeScript layer (virtual files) and an LSP layer (features).
- Under the hood, the Vue plugin relies on `@volar/code-gen` + `@volar/source-map` to keep every generated byte mapped back to the user’s SFC so diagnostics and quick fixes land in the right spot.

## Common Integration Paths

### 1. Shipping an LSP Server (VS Code, Neovim, Sublime)

1. Install `@volar/language-server`.
2. Create an `entry.ts` that calls `createLanguageServer` (or use `@volar/kit`’s CLI helpers) and forwards stdio (or node IPC) to the editor.
3. Provide configuration hooks so users can adjust `tsconfig`, Take Over Mode, and plugin toggles.

```ts
import { startLanguageServer } from '@volar/language-server/node';
import { createVolarService } from './tooling/createVolarService';

startLanguageServer(async (params) => ({
  languageService: createVolarService(params.initializationOptions.tsconfig),
}));
```

### 2. Embedding in a Browser Playground (Monaco)

1. Install `@volar/monaco`.
2. Register workers and configure virtual file resolution (fetch files over HTTP, from memory, etc.).
3. Attach the Volar language service to Monaco’s `languages.register` API.
4. For fully custom editors, use `@volar/editor` to avoid wiring the text-buffer plumbing from scratch.

### 3. Running Volar Inside a CLI

1. Build the service as shown earlier (or bootstrap via `@volar/kit` which wires file watching + reloads).
2. Call methods like `doValidation`, `findReferences`, or `format` on demand.
3. Perfect for codemods, lint rules, or CI checks that require Vue awareness without firing up an editor.

## How the Pieces Fit

- `@volar/language-core` owns **document truth** (what files exist, how they map).
- `@volar/code-gen` and `@volar/source-map` make sure generated TS/JS stays tied to the user’s original locations.
- `@volar/typescript` keeps Volar in sync with TS’s program graph.
- `@volar/language-service` exposes **capabilities** and loads **plugins**.
- Vue-specific packages (`@volar/vue-language-core`, `@volar/vue-language-service`, `@volar/vue-typescript`) ship the batteries-included feature set.
- Adapter packages (LSP, Monaco, Editor, Kit) connect those capabilities to a host protocol or runtime.
- Plugin packages (prefixed `volar-service-`) extend capabilities for CSS frameworks, formatting, component libraries, etc.

Think of it as layers: Core → Service → Adapter. When you extend Volar, you usually write a plugin for the service layer; when you embed it, you pick or author an adapter.

## Next Steps

1. Decide which host you are targeting (LSP editor vs browser vs CLI).
2. Scaffold a `createVolarService` helper shared across adapters.
3. Add the plugins you need (Prettier, Tailwind, custom diagnostics).
4. Document your initialization options so teams know how to tune Volar for their monorepo or tooling stack.

With these pieces in place you have a repeatable recipe for integrating any Vue-aware experience with the VolarJS ecosystem.

## Troubleshooting Cheatsheet

- **Take Over Mode conflicts** (`@volar/vue-typescript` vs plain TS LS): ensure only one TS server runs by disabling the built-in TypeScript extension (VS Code) or pointing Neovim/Sublime to the Volar TS plugin. Mixed servers lead to duplicate diagnostics.
- **`vue-tsc` misses project references**: pass the same `tsconfig.json` and `--project` path you hand to `createTypeScriptProject`; Volar piggybacks on TS incremental builds, so mismatched configs spawn duplicate programs.
- **Custom plugins not firing**: confirm they’re registered in both `language-core` (for embedded files) and `language-service` (for features). Many `volar-service-*` examples export `tsPlugin` and `languageService` to show both halves.
- **Broken source maps** after transforms: verify that every `codeGen.addText` call is paired with `codeGen.addMapping`. Leverage `@volar/source-map`’s `toGeneratedPositions` helpers to debug where a diagnostic lands.
- **High CPU in monorepos**: reach for `@volar/kit`’s file-watching filters (globs, `ignored`, `maxFileSize`) so unnecessary assets do not create snapshots. When embedding manually, reuse the same TS `DocumentRegistry`.