mirror of
https://github.com/LukeHagar/volar-docs.git
synced 2025-12-06 04:22:01 +00:00
63 lines
2.7 KiB
Markdown
63 lines
2.7 KiB
Markdown
# 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.
|