Volar YAML Language Service

Common errors

• Error: Cannot find module 'volar-service-yaml'

  cause The package is not installed or the import path is incorrect, or there's a module resolution issue in a mixed CJS/ESM project.
  fix Run `npm install volar-service-yaml` or `yarn add volar-service-yaml`. Double-check the import/require path. If using a custom Volar config, ensure Node.js can resolve the module in that context.

• TypeError: (0 , volar_service_yaml_1.create) is not a function

  cause This typically indicates an ESM/CommonJS interop issue where a CommonJS `require` is trying to access a named export like a default export, or vice-versa, or incorrect bundling.
  fix Ensure you are using the correct import syntax for your module environment. For `volar.config.js`, use `require('volar-service-yaml').create()`. For ESM TypeScript, use `import { create } from 'volar-service-yaml';`.

• Volar service 'yaml' failed to initialize: [...]

  cause The underlying `yaml-language-server` might be failing to start or encountering configuration errors.
  fix Check your editor's output channels for detailed errors from the Volar language server or the YAML language server. Verify your YAML files for syntax errors or invalid schema references. Ensure no conflicting YAML extensions are active.

Warnings

• breaking This plugin is designed for Volar v2.x and is not compatible with Volar v1.x (or the legacy 'Volar Language Features' VSCode extension). Attempting to use it with older Volar versions will lead to failures.
  Fix: Ensure your project and VSCode extension ('Vue - Official') are running Volar v2.x or newer. Migrate your Volar configuration if coming from v1.x.
• gotcha The `volar.config.js` file typically runs in a CommonJS environment, even if your project is otherwise ESM-enabled. Use `require()` for importing plugins within this configuration file.
  Fix: Stick to `require('volar-service-yaml').create()` in `volar.config.js`. If you use `volar.config.ts` with `ts-node` or similar, ESM imports (`import { create } from 'volar-service-yaml';`) might be necessary, but verify your specific setup.
• gotcha Incorrect or missing YAML schemas can lead to inaccurate diagnostics and missing auto-completion. The YAML Language Server relies on properly configured schemas.
  Fix: Review the documentation for `yaml-language-server` on how to configure schemas (e.g., via `.vscode/settings.json` or directly in YAML files) relevant to your project's YAML files.

Install

• npm install volar-service-yaml npm
• yarn add volar-service-yaml yarn
• pnpm add volar-service-yaml pnpm

Imports

• create
  wrong:

  import volarServiceYaml from 'volar-service-yaml';
  // or
  import { default as create } from 'volar-service-yaml';

  correct:

  import { create } from 'volar-service-yaml';

  For ESM environments or TypeScript projects. Volar v2 is ESM-first, so this is the recommended import style.
• create
  wrong:

  const create = require('volar-service-yaml').create;

  correct:

  const { create } = require('volar-service-yaml');

  CommonJS named import for Node.js environments, often used in `volar.config.js` files.
• ServicePlugin

  import type { ServicePlugin } from '@volar/language-service';

  This is a type import for defining a Volar service plugin, primarily for type-checking and autocompletion when creating custom services. Although not directly from `volar-service-yaml`, it's crucial for Volar plugin development.

Quickstart

Demonstrates how to integrate the YAML language service into your Volar configuration file to enable YAML features.

/* volar.config.js */
module.exports = {
	services: [
		require('volar-service-yaml').create(),
	],
};

// For a TypeScript-based Volar config (e.g., volar.config.ts with ts-node):
// import { create } from 'volar-service-yaml';
// import type { VolarConfig } from '@volar/language-service';
// export default <VolarConfig>{
// 	services: [
// 		create(),
// 	],
// };