Upgrade to Vite 7 (breaking change) #3417
Open
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Upgrades Hydrogen to require Vite 7.3.1+. This is a breaking change as
Vite 5 and 6 are no longer supported due to incompatible module runner
APIs. Implements critical fixes to MiniOxygen's module runner to handle
Vite 7's new SSR export mechanism.
## Breaking Changes
**Vite 7 is now required** - Vite 5 and 6 are no longer compatible
- Vite 7 added a 6th SSR parameter (ssrExportNameKey) that is incompatible
with Vite 6's 5-parameter structure
- Minimum Node.js version: 20.19.0 (was 18.0.0)
- Browser targets modernized: Chrome 107+, Safari 16+, Firefox 104+
## Migration Guide
Users must upgrade to Vite 7 before updating Hydrogen:
```bash
npm install vite@^7.0.0
```
## Key Changes
### Dependency Updates
- **BREAKING:** All Vite peer dependencies now require ^7.0.0 (was ^5.1.0 || ^6.2.1)
- Upgraded Vitest from ^1.0.4 to ^3.2.4 in @shopify/cli-hydrogen
- Added npm override to enforce Vite 7 across all packages
- Updated Node.js engine requirement to >=20.19.0
### MiniOxygen Vite 7 Compatibility Fixes
- Fixed missing __vite_ssr_exportName__ parameter (new 6th parameter in Vite 7)
- Added explicit parameter ordering to match Vite 7's esmEvaluator
- Implemented getBuiltins() invoke method handler (new in Vite 7)
- Removed deprecated 'root' option from ModuleRunnerOptions
- Cleaned up unused __VITE_ROOT environment variable
### Test Updates
- Updated build test expectations for Vite 7's new output format
("building client environment" vs "building for production")
## Why Vite 7 Only?
Vite 7's module runner has a fundamentally different parameter structure:
- **Vite 6**: 5 SSR parameters (no ssrExportNameKey)
- **Vite 7**: 6 SSR parameters (includes ssrExportNameKey)
Supporting both would require runtime version detection and dual code paths,
adding unnecessary complexity. Vite 7 is stable and provides better performance.
## Verification
- ✅ All packages build successfully with Vite 7.3.1
- ✅ 298/301 tests pass (99.4%)
- ✅ Dev server runs without errors
- ✅ TypeScript compilation passes
- ✅ @vitejs/plugin-react v4.3.4 compatible
## Related Issues
- Fixes Shopify#3263 - Add support for Vite 7 in @shopify/mini-oxygen
- Implements solution similar to cloudflare/workers-sdk#9773
Documents breaking changes: - Vite 7.0.0+ required (Vite 5/6 no longer supported) - Node.js 20.19.0+ required - Migration guide for users - Technical rationale for Vite 7 only approach
frandiox
reviewed
Jan 27, 2026
Contributor
frandiox
left a comment
frandiox
left a comment
There was a problem hiding this comment.
Thanks for the PR!
I haven't tested this but the changes make sense from what I remember, at least as an interim solution. Eventually we should upgrade to the new Vite Environment API cc @fredericoo @kdaviduik
Note: Node.js upgrade probably should come first in another PR (there's already one for this I think).
Contributor
Author
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
WHY are these changes introduced?
Fixes #3263
The
@shopify/mini-oxygenpackage is incompatible with Vite 7.x due to SSR implementation differences, causingReferenceError: __vite_ssr_exportName__ is not defined. This blocks developers from using Vite 7.Vite 7 introduces breaking changes to the Module Runner API:
ssrExportNameKeyas a 6th parameter to the SSR contextgetBuiltins()invoke methodrootoption from ModuleRunnerOptionsWHAT is this pull request doing?
Core changes to
@shopify/mini-oxygen(src/vite/worker-entry.ts):ssrExportNameKey(new 6th parameter in Vite 7)runInlinedModuleto use 6 parameters matching Vite 7's esmEvaluatorgetBuiltins()invoke methodRemoved deprecated feature (
server-middleware.ts):__VITE_ROOTbinding (deprecated in Vite 7)Package updates:
@shopify/mini-oxygen^7.0.0, Node>=20.19.0@shopify/cli-hydrogen^7.0.0, Vitest^3.2.4@shopify/hydrogen^7.0.0@shopify/hydrogen-react^7.0.0templates/skeleton^7.0.0>=20.19.0, Vite override^7.0.0Test updates:
build.test.ts: Updated assertions for Vite 7's changed output messagesHOW to test your changes?
Run mini-oxygen tests:
npm test -- --filter=@shopify/mini-oxygenExpected: 47 tests pass
Build the skeleton template:
Expected: Successful build
Run cli-hydrogen tests:
npm test -- --filter=@shopify/cli-hydrogenExpected: 297/298 pass (1 pre-existing failure unrelated to Vite 7)
Checklist