feat!: vite 7 support to mini-oxygen by ramonclaudio · Pull Request #3493 · Shopify/hydrogen

ramonclaudio · 2026-02-23T15:42:25Z

WHY are these changes introduced?

I opened #3263 in October when Vite 7 broke mini-oxygen with ReferenceError: __vite_ssr_exportName__ is not defined. @thomasKn opened #3417 in January with a fix, but @frandiox suggested waiting for #3404 (Node version bump) to merge first. #3404 merged on Feb 17 but #3417 was never rebased, and now it conflicts with 62 commits that landed since (the 2026.1.0 release, security dep bumps, calver infrastructure changes, the docs/preview migration to React Router 7, etc).

the core worker-entry.ts fix in #3417 was correct so this PR applies the same approach rebased on current main. @thomasKn is credited as co-author on the commit.

from thomasKn's #3417:

import ssrExportNameKey and use all 6 SSR context keys in explicit order
handle getBuiltins() invoke method (returns empty array for workerd)
remove root from ModuleRunnerOptions and __VITE_ROOT from bindings
vite peer/dev dep bumps and build test updates

added in this PR:

rebased onto current main (62 commits of conflicts resolved)
restructured fetchModule() dispatch to route by customData.name instead of treating every custom invoke as a fetch. the old code also had a bug where it passed the method name ("fetchModule") as the importer param instead of the actual importer from customData.data[1]
added docs/upgrade-guides/upgrading-to-vite-7.md
bumped docs/preview/package.json to Vite 7 (missed in Upgrade to Vite 7 (breaking change) #3417)
bumped packages/cli/assets/vite/package.json to Vite 7 so shopify hydrogen setup vite doesn't scaffold a Vite 6 project that immediately breaks
fixed CONTRIBUTING.md (said Node 16.14.0, should be 22+)
changeset with migration guide and browser target comparison table
changed workspace:* to workspace:^ in cli-hydrogen peerDeps so they publish as caret ranges (matching previous behavior)

the root cause: Vite 7 added ssrExportNameKey as a 6th parameter to runInlinedModule. mini-oxygen was using Object.keys(context) to build the parameter list, which worked in Vite 5/6 (5 params) but breaks in Vite 7 because the parameter ordering no longer matches what the transformed SSR code expects.

ReferenceError: __vite_ssr_exportName__ is not defined

Vite 7 also removed the root option from ModuleRunnerOptions and added a getBuiltins() invoke method. both need handling.

WHAT is this pull request doing?

packages/mini-oxygen/src/vite/worker-entry.ts:

import all 6 named SSR keys from vite/module-runner (ssrModuleExportsKey, ssrImportMetaKey, ssrImportKey, ssrDynamicImportKey, ssrExportAllKey, ssrExportNameKey) and pass them in explicit order instead of Object.keys(context) / Object.values(context)
handle getBuiltins() invoke method (returns empty array, no builtins in workerd)
restructure fetchModule() dispatch to use customData.name matching and fix the importer bug
remove root from ModuleRunnerOptions (removed in Vite 7)
remove __VITE_ROOT from ViteEnv interface

packages/mini-oxygen/src/vite/server-middleware.ts:

remove __VITE_ROOT binding

packages/cli/src/commands/hydrogen/build.test.ts:

Vite 7 changed build log format: building for production is now building client environment for production, building SSR bundle for production is now building ssr environment for production

version bumps across 6 package.json files. vite peer/dev deps updated from various Vite 5/6 ranges (^5.1.0 || ^6.2.x, ^6.2.x, etc) to ^7.0.0. vitest and @vitest/coverage-v8 bumped from ^1.0.4 to ^3.2.4 in cli-hydrogen.

also:

added docs/upgrade-guides/upgrading-to-vite-7.md
fixed CONTRIBUTING.md (said Node 16.14.0, should be 22+)
changeset with migration guide

before:

ReferenceError: __vite_ssr_exportName__ is not defined
    at worker-entry.ts

after:

pnpm dev
# works

HOW to test your changes?

pnpm install && pnpm run build
pnpm run typecheck
pnpm run lint
pnpm run format -- --check
pnpm run test

cli-hydrogen: 315 passed, 6 skipped, 0 failures. full suite across all packages: 1,318 passed, 12 skipped, 0 failures. typecheck/lint/format clean.

Notes

Vite 5 and 6 support is dropped. the module runner parameter structure changed from 5 to 6 params with no backwards-compatible way to detect which version you're on at build time.

@frandiox mentioned migrating to the Vite Environment API eventually. that's a separate thing. this just gets people off the __vite_ssr_exportName__ error.

Checklist

I've read the Contributing Guidelines
I've considered possible cross-platform impacts (Mac, Linux, Windows)
I've added a changeset if this PR contains user-facing or noteworthy changes
I've added tests to cover my changes
I've added or updated the documentation

ramonclaudio · 2026-02-23T16:02:21Z

I have signed the CLA!

.changeset/vite-7-upgrade.md

fredericoo

we have just now finished migrating from npm to pnpm

can you merge main into this branch and revisit a few parts:

overrides no longer exists in package.json
do we need to override vite’s version? which peer/transitive deps could break because of this?

Fixes Shopify#3263 Vite 7 changed the Module Runner API in ways that break mini-oxygen's SSR evaluation. This adds the missing ssrExportNameKey (6th param), handles the new getBuiltins() invoke method, removes the deprecated root option from ModuleRunnerOptions, and bumps all vite peer deps across the monorepo. Also adds a migration guide and fixes the outdated Node version in CONTRIBUTING.md. Co-authored-by: Thomas Cristina de Carvalho <thomas@frontvibe.com>

hydrogen-react has zero runtime Vite dependency — the built output contains no import.meta, HMR, or Vite globals. Widening the peer dep to ^5.1.0 || ^6.2.1 || ^7.0.0 is non-breaking for existing users. Split into a separate changeset to avoid inheriting the inaccurate "Vite 5 and 6 support removed" CHANGELOG description.

All workspace packages already declare vite@^7.0.0 directly. The ^6.2.1 override (carried over from the npm->pnpm migration) would have forced vite 6.x across the workspace, breaking the Vite 7 upgrade.

Lockfile was stale after removing the vite ^6.2.1 workspace override in 134a1a5. Regenerated to resolve vite 7.x versions workspace-wide.

ramonclaudio · 2026-02-24T16:40:08Z

Done @fredericoo. Also regenerated pnpm-lock.yaml, it was stale after removing the old vite: ^6.2.1 workspace override.

ramonclaudio · 2026-02-25T13:42:07Z

Bumped packages/cli/assets/vite/package.json from ^6.2.0 -> ^7.0.0 so vite scaffold doesn't break.

docs/upgrade-guides/upgrading-to-vite-7.md

Storefronts depend on @shopify/cli, not @shopify/cli-hydrogen directly.

- Remove fabricated npm 11.6.2+ prerequisite from upgrade guide - Remove misleading Vitest section (was already required before Vite 7) - Change npm commands to pnpm in upgrade guide and changeset - Use workspace:^ instead of workspace:* in cli-hydrogen peerDeps to publish as caret ranges (matching previous behavior)

- Vitest ^3.2.4 was already required before Vite 7 - "Why Vite 7 only?" section was internal engineering detail, not merchant-facing

fredericoo

last round! it all passes tests and i could manually assure it all works fine on vite 7.

.changeset/vite-7-upgrade.md

pnpm-workspace.yaml

frandiox · 2026-03-25T10:53:24Z

@ramonclaudio hey! thanks a lot for the work here. I was checking the new Vite's environment API and it seems like it would allow us to support Vite 8 without breaking changes for Vite 6 and 7. There's a draft here.

Would you be able to check that PR and see if it works for your project? 🙏

ramonclaudio · 2026-03-27T17:26:41Z

Hey @frandiox. The Vite Environment API approach is the right call here. I went ahead and built @shopify/mini-oxygen, @shopify/hydrogen, and @shopify/hydrogen-react from fd-vite-8 and validated #3617 end-to-end.

Tested on a real storefront using the shopify-hydrogen-shadcn-template, my open source port of the default hydrogen init skeleton to shadcn/ui. The feat/vite-8-env-api branch has #3617 applied and ready to run if you'd like to test it on a mock shop.

Build and dev server pass on Vite 6.4.1, 7.3.1, and 8.0.3. All routes 200 with live Storefront API data. HMR works. Zero console errors.

I also added pnpm patches to my patches repo, if you want to test the changes on another project:

frandiox · 2026-03-27T17:44:30Z

@ramonclaudio Amazing, thank you so much for the thorough test! 🙇

ramonclaudio · 2026-03-27T18:52:56Z

@frandiox NP. Happy to help!

ramonclaudio requested a review from a team as a code owner February 23, 2026 15:42

github-actions bot added the cla-needed label Feb 23, 2026

github-actions bot removed the cla-needed label Feb 23, 2026

fredericoo reviewed Feb 24, 2026

View reviewed changes

.changeset/vite-7-upgrade.md Outdated Show resolved Hide resolved

fredericoo reviewed Feb 24, 2026

View reviewed changes

ramonclaudio and others added 2 commits February 24, 2026 11:18

ramonclaudio force-pushed the feat/vite-7-upgrade branch from 0830857 to 6f489f5 Compare February 24, 2026 16:18

ramonclaudio added 2 commits February 24, 2026 11:21

fix: remove stale vite override from pnpm-workspace.yaml

134a1a5

All workspace packages already declare vite@^7.0.0 directly. The ^6.2.1 override (carried over from the npm->pnpm migration) would have forced vite 6.x across the workspace, breaking the Vite 7 upgrade.

fix: regenerate pnpm-lock.yaml after vite override removal

3addde3

Lockfile was stale after removing the vite ^6.2.1 workspace override in 134a1a5. Regenerated to resolve vite 7.x versions workspace-wide.

ramonclaudio mentioned this pull request Feb 24, 2026

feat(@shopify/hydrogen): add Vite 7 patches for PR #3493 ramonclaudio/patches#5

Merged

fix: bump vite to ^7.0.0 in setup vite asset template

5086c43

ramonclaudio requested a review from fredericoo February 25, 2026 13:44

fredericoo reviewed Mar 11, 2026

View reviewed changes

docs/upgrade-guides/upgrading-to-vite-7.md Outdated Show resolved Hide resolved

fredericoo changed the title ~~Add Vite 7 support to mini-oxygen~~ feat!: vite 7 support to mini-oxygen Mar 11, 2026

ramonclaudio added 3 commits March 12, 2026 15:51

fix(docs): remove cli-hydrogen from troubleshooting install command

91212a5

Storefronts depend on @shopify/cli, not @shopify/cli-hydrogen directly.

fix(changeset): remove misleading Vitest section and internal rationale

b065694

- Vitest ^3.2.4 was already required before Vite 7 - "Why Vite 7 only?" section was internal engineering detail, not merchant-facing

ramonclaudio requested a review from fredericoo March 12, 2026 20:34

Merge branch 'main' into feat/vite-7-upgrade

bf96327

fredericoo requested changes Mar 20, 2026

View reviewed changes

.changeset/vite-7-upgrade.md Show resolved Hide resolved

fix(changeset): add skeleton and create-hydrogen to changeset

1130fd6

fredericoo reviewed Mar 20, 2026

View reviewed changes

pnpm-workspace.yaml Show resolved Hide resolved

ramonclaudio added 2 commits March 20, 2026 07:41

fix: use vite catalog and override instead of hardcoded versions

34ecb38

merge: resolve upstream/main conflicts and regenerate lockfile

d0bb762

ramonclaudio requested a review from fredericoo March 22, 2026 14:25

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat!: vite 7 support to mini-oxygen#3493

feat!: vite 7 support to mini-oxygen#3493
ramonclaudio wants to merge 12 commits intoShopify:mainfrom
ramonclaudio:feat/vite-7-upgrade

ramonclaudio commented Feb 23, 2026 •

edited

Loading

Uh oh!

ramonclaudio commented Feb 23, 2026

Uh oh!

Uh oh!

fredericoo left a comment

Uh oh!

ramonclaudio commented Feb 24, 2026

Uh oh!

ramonclaudio commented Feb 25, 2026

Uh oh!

Uh oh!

fredericoo left a comment

Uh oh!

Uh oh!

Uh oh!

frandiox commented Mar 25, 2026

Uh oh!

ramonclaudio commented Mar 27, 2026

Uh oh!

frandiox commented Mar 27, 2026 •

edited

Loading

Uh oh!

ramonclaudio commented Mar 27, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

ramonclaudio commented Feb 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

WHY are these changes introduced?

WHAT is this pull request doing?

HOW to test your changes?

Notes

Checklist

Uh oh!

ramonclaudio commented Feb 23, 2026

Uh oh!

Uh oh!

fredericoo left a comment

Choose a reason for hiding this comment

Uh oh!

ramonclaudio commented Feb 24, 2026

Uh oh!

ramonclaudio commented Feb 25, 2026

Uh oh!

Uh oh!

fredericoo left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

frandiox commented Mar 25, 2026

Uh oh!

ramonclaudio commented Mar 27, 2026

Uh oh!

frandiox commented Mar 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ramonclaudio commented Mar 27, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

ramonclaudio commented Feb 23, 2026 •

edited

Loading

frandiox commented Mar 27, 2026 •

edited

Loading