# Migrating from Vetur to Volar

> [Docs Index](README.md) • [Repo README](../README.md) • [Configuration & Projects](configuration-and-projects.md) • [Testing & CI](testing-and-ci.md)

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:

```json
{
  "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)

```json
{
  "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](cli-integration.md)).

## 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

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

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