Migrating from Vetur to Volar

Docs Index • Repo README • Configuration & Projects • Testing & CI

Many Vue projects still rely on Vetur (the legacy VS Code extension). This guide walks through migrating to Volar, highlighting feature differences, configuration updates, and gotchas.

Why Switch?

Capability	Vetur	Volar
`<script setup>` support	Limited	Full (type inference, macros)
Take Over Mode	No	Yes (shared TS server)
Template type checking	Partial	Full (TS-based)
Performance	Slower on large projects	Designed for monorepos + incremental diagnostics

Migration Steps

1. Install Volar Extension

In VS Code, install “Vue Language Features (Volar)” and disable Vetur:

{
  "vetur.validation.template": false,
  "vetur.completion.autoImport": false,
  "vetur.experimental.templateInterpolationService": false
}

Or disable the entire Vetur extension via the Extensions panel.

2. Enable Take Over Mode (Optional)

{
  "volar.takeOverMode.enabled": true,
  "volar.tsPlugin": true
}

Disable VS Code’s built-in TypeScript server to avoid duplicate diagnostics.

3. Update `tsconfig.json`

Include .vue files ("include": ["src/**/*.vue", "src/**/*.ts"]).
Set allowJs and allowNonTsExtensions to true.
Add "types": ["vue"].

4. Remove Vetur-specific Settings

Delete .vscode/settings.json entries for vetur.*.
Replace Vetur formatting with Prettier or volar-service-prettier.

5. Verify Diagnostics

Open representative .vue files and confirm template diagnostics, completions, hover, and go-to-definition work as expected.

6. Update CI/CLI

Replace vti diagnostics or Vetur-specific scripts with vue-tsc --noEmit or a Volar CLI (CLI Integration).

Common Issues

Issue	Fix
Duplicate diagnostics	Disable Vetur + built-in TS server; enable Take Over Mode.
Missing `<i18n>` completions	Install `volar-service-json` or vue-i18n Volar plugin.
Formatting changed	Configure Prettier or install `volar-service-prettier`.
Legacy Vue 2 project	Use Volar’s compatibility mode (`vueCompilerOptions.target = 2.7`) or keep Vetur until upgrade.

Advanced Tips

Auto Switch Prompt: Set "volar.autoSwitchToTakeOverMode": true to prompt users when features require Take Over Mode.
Monorepos: Use multi-root workspaces so each package loads its own tsconfig—Vetur often guessed, Volar requires explicit configs.
Telemetry: Emit a warning when the server detects Vetur still running to encourage full migration.

Verification Checklist

<script setup> macros show inferred types.
Template completions list component props/slots.
Diagnostics align between editors and CI.
No duplicate errors.

Document these steps in your project README to help contributors migrate smoothly.

3.0 KiB Raw Permalink Blame History Unescape Escape