Version Pinning vs. Compatibility Shims for Upgrade Recovery

Short answer

Pin back first, shim second. When a Vite major upgrade breaks plugin APIs, restore the last known-good versions from your committed lockfile, verify both dev and build pass, and only then re-attempt the upgrade incrementally. Treat Vite's deprecated/legacy APIs as a transition window, not a recovery strategy.

Why pinning is the safer recovery

Vite's dev server and build pipeline share the same core, so mixing major versions of vite and first-party plugins (for example @vitejs/plugin-react) is a common source of HMR failures and asset emission errors. Keeping them on the same major line is the baseline requirement, and a strict pin plus a committed lockfile makes that state reproducible: rollback is just restoring the lockfile and reinstalling.

Two caveats on pinning:

• A semver range like ^5.0.0 in package.json can silently pull a newer minor on the next install even with a lockfile present, depending on the package manager. Use exact versions, or a package-manager override/resolution field for transitive dependencies.
• There is no official vite upgrade migration script that reverts versions. Migration and rollback are manual: edit package.json, reinstall, consult the migration guide for the specific major you are crossing.

Where shims fall short

Deprecated APIs exist to ease migration, not to guarantee identical behavior. The risky case is exactly the one you flagged: a shim can keep a plugin loading without a hard error while its transform output or module-graph assumptions no longer match the new core. Because dev (esbuild-based) and production (Rollup-based) pipelines differ, a green dev server does not prove the build is correct. HMR desynchronization typically appears when editing a module covered by the affected plugin serves a stale or mismatched module instead of a clean hot update.

Recovery procedure

1. Restore the pinned versions and lockfile from version control, delete node_modules, and reinstall from the lockfile.
2. Run both vite dev and vite build to confirm the known-good state is reproduced.
3. Diff vite.config before and after the downgrade. Whether custom resolver configuration survives a revert depends entirely on your own version control of the config file — nothing in the tooling preserves it for you.
4. Re-attempt the upgrade on a branch, one plugin at a time, starting with the plugin whose API changed.
5. Before merging, smoke-test the emitted build: compare hashed asset names and the chunk graph across the upgrade, and edit a module covered by the suspect plugin to confirm the browser receives a hot update rather than a stale chunk or full reload.

Uncertainty

Exact deprecation windows and plugin API changes are version-specific; check the migration guide for the major you are crossing rather than assuming a shim exists for your plugin. If you can share which plugin broke and the from/to versions, the recommendation may shift — some plugin majors are explicitly co-versioned with Vite and must move together, which would argue for a full coordinated pin rather than a partial shimmed upgrade.