# Upgrading VolarJS: Release & Compatibility Guide

> [Docs Index](README.md) • [Repo README](../README.md) • [Testing & CI](testing-and-ci.md) • [Performance Guide](performance-and-debugging.md)

This guide outlines a safe upgrade path when bumping Volar, TypeScript, or Node versions across your tooling.

## Version Matrix

| Volar Major | Recommended TS | Minimum Node | Notes |
| --- | --- | --- | --- |
| 1.x | 4.9–5.0 | Node 14+ | Legacy support for Vue 2 + early Vue 3. |
| 2.x | 5.0–5.4 | Node 16+ | Current stable; aligns with Vue 3.4+. |
| 3.x (alpha) | 5.4+ | Node 18+ | Experimental features (volar-next). |

Always align `@volar/*`, `@vue/language-*`, and `typescript` versions to the matrix above.

## Upgrade Checklist

1. **Pin Dependencies** – update `package.json` to the target versions; use exact versions for deterministic builds.
2. **Update Tooling** – ensure VS Code extension, CLI, and server dependencies all reference the same Volar release.
3. **Run Tests** – execute unit/integration tests (see [Testing & CI](testing-and-ci.md)).
4. **Benchmark** – re-run performance benchmarks (see [LSP Benchmarking](lsp-benchmarking.md)).
5. **Smoke Test Editors** – open representative projects in VS Code/Neovim/etc.
6. **Document Changes** – highlight breaking changes or new config fields in your release notes.

## Handling Breaking Changes

- **Config**: When introducing new settings (e.g., `volarJsonYaml.schemas`), provide defaults and migration instructions.
- **APIs**: If your custom plugins rely on Volar internals, watch release notes for API removals/renames and adapt accordingly.
- **TypeScript**: Major TS upgrades may require updating `tsconfig` (e.g., new `lib` entries) and re-running `tsc --build`.

## Testing Multiple Versions

Use `npm` aliases or `pnpm overrides` to test against multiple Volar/TS combos:

```bash
npm install typescript@5.0 @volar/language-service@2.2.1
npm test
npm install typescript@5.4 @volar/language-service@2.4.0
npm test
```

Automate via CI matrix:

```yaml
strategy:
  matrix:
    ts: ["5.0", "5.4"]
    volar: ["2.2.1", "2.4.0"]
```

## Deprecations

- Monitor [release notes](https://github.com/vuejs/language-tools/releases) for deprecations (e.g., old config flags, plugin APIs).
- When a feature is deprecated, surface warnings in your logs and plan migrations ahead of the removal.

## Communication

- Publish a migration guide whenever you bump major versions—include new settings, removal of flags, and compatibility notes.
- For consumers of your tooling, provide sample upgrade scripts (e.g., `npx volar-migrate`).

Staying proactive with upgrades keeps your tooling aligned with Vue’s evolution and prevents users from encountering surprise regressions.