Vue Language Server (VLS)

Common errors

• vls: command not found

  cause The `vls` executable is not installed globally or is not in the system's PATH.
  fix Install `vls` globally using `npm install -g vls` or `yarn global add vls`.

• Error: Cannot find module 'vls/dist/vueServerMain'

  cause A language client attempted to resolve the `vueServerMain` entry point but `vls` is not installed as a local dependency or the path is incorrect.
  fix Ensure `vls` is installed as a local dependency (`npm install vls --save` or `yarn add vls`) in the project where the language client is running.

Warnings

• breaking The `vls` package, and by extension the Vetur VS Code extension it powered, provides only basic and incomplete support for modern Vue 3 features, particularly `<script setup>`, Composition API refinements, and advanced TypeScript integration. Many Vue 3-specific language features will not function correctly or at all.
  Fix: For full language tooling support in Vue 3 projects, it is strongly recommended to migrate to Volar (e.g., the 'Vue Language Features (Volar)' extension for VS Code).
• deprecated The `vls` npm package at version `0.8.5` has not been updated for an extended period and is considered deprecated for modern Vue.js development. While the Vetur extension historically used `vls` as its core, Vetur itself now explicitly recommends Volar for Vue 3 projects, indicating a shift in the ecosystem.
  Fix: For all new Vue projects, especially those using Vue 3, it is advised to use Volar. For legacy Vue 2 projects, be aware that VLS/Vetur might not receive further updates or bug fixes.
• gotcha The `vls` package explicitly requires Node.js version `10` or higher to run, as specified in its `engines` field. Attempting to run `vls` with older Node.js versions will prevent the language server from starting or cause unexpected errors.
  Fix: Ensure your Node.js environment is version 10 or greater. Update Node.js if necessary using a version manager like `nvm` or `volta`.

Install

• npm install vls npm
• yarn add vls yarn
• pnpm add vls pnpm

Imports

• vls (CLI command)
  wrong:

  import { vls } from 'vls'

  correct:

  npm install -g vls
  vls --version

  `vls` is primarily consumed as a global CLI command for direct user interaction or spawned by language client extensions, rather than being imported as a module into application code.
• vueServerMain
  wrong:

  import { vueServerMain } from 'vls/dist/vueServerMain'

  correct:

  require.resolve('vls/dist/vueServerMain')

  This path points to the server's main executable script. It is typically used programmatically by language client implementations with `child_process.spawn('node', [require.resolve('vls/dist/vueServerMain')])` to launch the language server process.
• VLS (type)
  wrong:

  import { VLS } from 'vls'

  correct:

  import type { VLS } from 'vls'

  For TypeScript users developing custom language client extensions or programmatically interacting with VLS, its type definitions can be imported. This is a type-only import and does not provide runtime values.

Quickstart

Demonstrates how to install VLS globally via CLI and conceptually how a language client would spawn the `vls` server process for LSP communication.

npm install -g vls

# Verify installation and server functionality
vls --version

# Example of how a language client might launch it (conceptual)
const { spawn } = require('child_process');
const path = require('path');

const vlsPath = require.resolve('vls/dist/vueServerMain');
console.log(`Attempting to start VLS from: ${vlsPath}`);

const serverProcess = spawn('node', [vlsPath], {
  stdio: ['pipe', 'pipe', 'pipe'] // stdin, stdout, stderr for LSP communication
});

serverProcess.stdout.on('data', (data) => {
  console.log(`VLS STDOUT: ${data.toString().trim()}`);
});

serverProcess.stderr.on('data', (data) => {
  console.error(`VLS STDERR: ${data.toString().trim()}`);
});

serverProcess.on('exit', (code) => {
  console.log(`VLS process exited with code ${code}`);
});

// In a real client, you'd send LSP messages to serverProcess.stdin
// and parse responses from serverProcess.stdout.