Vite Version Compatibility Reference

This page pins which Vite major works with which Node runtime, which Rollup version it vendors, and which @vitejs/plugin-react/@vitejs/plugin-vue releases are safe to pair with it — so an upgrade does not strand you on an EOL Node or an incompatible plugin. It belongs to the broader Vite Configuration & Ecosystem and is the version companion to that overview’s runtime and plugin guidance. The data below covers Vite 4.x, 5.x, and 6.x, the breaking changes each major introduced (Vite 5’s Node 18 floor and Rollup 4 swap, Vite 6’s Environment API), and the deprecations to clear before bumping.

What This Page Pins and Why

Vite vendors Rollup and esbuild internally, so the Rollup version is not something you choose — it ships inside the vite package, and a Rollup major bump (3 → 4 in Vite 5) changes output hashing, manualChunks semantics, and plugin context APIs. Node compatibility matters because Vite’s config loader and import.meta handling rely on runtime ESM features that only stabilised in specific Node lines; running Vite 5 on Node 16 fails at startup with Vite requires Node.js version 18. The framework plugins (@vitejs/plugin-react, @vitejs/plugin-vue) declare a vite peer range, and mismatches surface as Failed to resolve entry for package or HMR that silently degrades to full reloads. Pin all three together.

Vite ↔ Node ↔ Rollup Matrix

Node lines listed as 18.18 / 20.19 mean Vite refuses to start on patch releases below those within each major line; Vite 6 dropped Node 21 (a non-LTS odd line) entirely. esbuild ranges are the versions Vite vendored across that major’s lifetime — you do not install esbuild directly, but a globally-installed mismatched esbuild can shadow it and throw Host version does not match binary version.

Vite ↔ Framework Plugin Matrix

Installing @vitejs/plugin-react@3 against Vite 5 produces The following dependencies are imported but could not be resolved or an HMR boundary that never engages. When in doubt, install the plugin without a pin (npm i -D @vitejs/plugin-react) and let npm resolve against your vite version, then lock the result.

Breaking Changes by Major

Vite 5 (Node 18+, Rollup 4)

• Node 18.18+ required. Node 14 and 16 dropped. The CLI hard-exits on older runtimes.
• Rollup 3 → 4. Output filename hashing changed, so cache keys and Subresource Integrity hashes shift even with no source change — expect a one-time cache bust on CDNs. manualChunks returning a falsy value now reliably falls through to default chunking.
• build.polyfillModulePreload removed, replaced by build.modulePreload. The old key is ignored silently.
• CJS Node API deprecated. Importing Vite’s API via require('vite') warns; the build still works but the path is on notice for removal.
• define no longer stringifies values that are already strings in some edge cases — audit any define that injected JSON.

Vite 6 (Environment API)

• Environment API (experimental). A first-class environments config replaces ad-hoc ssr/client branching inside plugins. The legacy ssr options still work, but plugin authors should read this.environment rather than the old options.ssr boolean. This affects the branching patterns in advanced Vite plugin configuration.
• Node 21 dropped; 18.18 / 20.19 / 22.12 floors. Odd-numbered non-LTS lines are no longer supported targets.
• resolve.conditions defaults changed. The default condition order now includes module ahead of browser in more cases, which can change which export a dual-package resolves to. Re-test ESM/CJS interop after upgrading.
• Sass legacy API removed by default in favour of the modern sass-embedded API; projects using additionalData with legacy syntax must migrate.
• build.cssMinify and worker config gained per-environment overrides.

Upgrade and Migration Notes

1. Bump Node first. Move to the recommended LTS for your target Vite major before touching vite itself; most upgrade failures are actually Node-floor failures.
2. Upgrade Vite and framework plugins together, in one package.json change, then rm -rf node_modules/.vite to clear the pre-bundle cache, which is keyed to the old Vite version.
3. Re-run the build and diff dist/. The Rollup 3 → 4 jump (Vite 4 → 5) changes content hashes; confirm only hashes moved, not chunk membership, with ls -1 dist/assets | sort.
4. For Vite 6, audit plugin SSR branching. Replace transform(code, id, { ssr }) reads with this.environment.name where you adopt the Environment API; the old signature still functions during the deprecation window.
5. Re-validate library builds. Output hashing and exports resolution interact — re-run publint after upgrading if you ship a package via Vite library mode.

Deprecations to Clear Before Upgrading

• build.polyfillModulePreload → build.modulePreload (removed in 5).
• require('vite') CJS entry → ESM import (deprecated in 5).
• Legacy Sass API / sass package → sass-embedded (default flipped in 6).
• Plugin reads of options.ssr → this.environment (soft-deprecated in 6).
• import.meta.glob as option → query/import options (deprecated across 5.x).

Related

• Vite Configuration & Ecosystem — the parent overview whose dev-server, plugin, and build guidance assumes the versions pinned here.
• Vite library mode and package bundling — where the bundled Rollup version directly affects output hashing and exports resolution.
• Advanced Vite plugin configuration — affected by the Vite 6 Environment API change to SSR branching.
• Understanding ESM vs CommonJS in modern bundlers — context for the resolve.conditions default change in Vite 6.