volar-docs/docs/volar-service-catalog.md

Volar Service Catalog (volar-service-*)

Docs Index • Repo README • Plugin Authoring • Testing & CI

Volar services (volar-service-*) are language-service plugins that extend Volar with extra capabilities—formatting, Emmet support, CSS completions, etc. This catalog documents the most common services, how to configure them, and how to evaluate compatibility for custom stacks.

How Services Plug In

Services implement the LanguageServicePlugin interface and are typically registered in two places:

1. Language Server (@volar/language-server): pass them in when creating the project.
2. Client Configuration: give users toggles (enable/disable, options).

Example:

import { createLanguageService } from '@volar/language-service';
import volarServiceEmmet from 'volar-service-emmet';
import volarServicePrettier from 'volar-service-prettier';

const service = createLanguageService(language, [volarServiceEmmet(), volarServicePrettier()], env, project);

Official Services

Package	Capability	Notes
volar-service-css	CSS/SCSS/Less completions, diagnostics, hover in <style> blocks	Configurable via languages + scopedModules.
volar-service-emmet	Emmet abbreviations inside template/style regions	Enable per workspace; configurable snippet profiles.
volar-service-html	HTML attribute/tag completions for templates	Works alongside Vue component completion; helpful for custom elements.
volar-service-json	JSON completions/hover for <i18n> blocks	Targets embedded JSON sections.
volar-service-prettier	Formatting for templates/scripts/styles via Prettier	Respects .prettierrc; expose settings for singleQuote, semi, etc.
volar-service-typescript	TypeScript-based completions/diagnostics	Powers TS-specific features (import completions, quick fixes).
volar-service-typescript-twoslash-queries	Inline ^? twoslash queries (type exploration)	Great for REPLs/docs; disable in production editors if noise.
volar-service-pug / volar-service-pug-beautify	Pug template support + formatting	Use when <template lang="pug">.

All official packages live under vuejs/language-tools.

Community Services (Examples)

Package	Capability	Maintainer
@volar-plugins/tailwind	Tailwind class name completions/diagnostics	Windi/Tailwind community
@volar-plugins/i18n	Vue I18n completions + diagnostics	Intlify
@vue-macros/volar	Macro support (defineSlots, betterDefine)	Vue Macros
volar-service-astro (conceptual)	Astro component support (example patterns)	Astro community

When adopting community services:

• Audit compatibility with your Volar version (check peer dependencies).
• Review configuration options—they often expose toggles for strictness or frameworks.

Configuration Pattern

Expose service-specific settings via your LSP server:

type MyConfig = {
  emmet?: {
    enabled: boolean;
    showExpandedAbbreviation?: boolean;
  };
  prettier?: {
    semi?: boolean;
    singleQuote?: boolean;
  };
};

const services = [
  volarServiceEmmet(() => config.emmet ?? { enabled: true }),
  volarServicePrettier(() => config.prettier),
];

On config changes, re-create the service or update its options.

Compatibility Matrix

Service	Works With	Notes
CSS/HTML/JSON	All editors (VS Code, Neovim, Sublime)	No extra dependencies.
Prettier	Requires Prettier dependency in workspace or bundled version	Provide fallback if Prettier missing.
Emmet	Works best in editors with Emmet disabled (to avoid double expansion)	Document instructions for VS Code (“disable built-in Emmet for Vue files”).
Tailwind/Windi	Requires project-level config (tailwind.config.js)	Cache parse results across files.
I18n	Requires Vue I18n dependency; scans locale files	Provide configuration for locale file globs.

Service Development Tips

1. Start from templates – use official services as references; they showcase best practices.
2. Split TS vs LSP logic – if your service manipulates TS AST, keep code in a separate module so it can be reused in TS plugins.
3. Provide diagnostics source – set diagnostic.source = 'your-service' so users can filter.
4. Respect cancellation tokens – service hooks may run frequently; bail out if token.isCancellationRequested.
5. Expose config – allow users to toggle features to avoid conflicts (e.g., Emmet vs built-in Emmet).

Discoverability

• Monitor the Volar Discussions and Awesome Volar (if maintained) for new services.
• Encourage plugin authors to publish README snippets describing how to register the service with LSP clients (settings JSON, init options).

With this catalog and configuration guidance, you can confidently assemble the right mix of Volar services—or build your own—to deliver rich editor experiences tailored to your stack.