volar-docs/docs/release-and-upgrade.md

Upgrading VolarJS: Release & Compatibility Guide

Docs Index • Repo README • Testing & CI • Performance Guide

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).
4. Benchmark – re-run performance benchmarks (see LSP Benchmarking).
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:

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:

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

Deprecations

• Monitor release notes 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.