Make Oxygen deployment flows standalone by frandiox · Pull Request #3819 · Shopify/hydrogen

frandiox · 2026-06-25T15:43:02Z

Summary

make the Mini Oxygen Vite plugin infer compatibility dates and work without Hydrogen plugin coordination
support standalone Oxygen deploy output resolution and configurable deploy output directories
add Mini Oxygen Vite preview runtime and Vite env fallback when CLI/plugin env is not provided

Validation

pnpm --dir packages/mini-oxygen run typecheck
pnpm --dir packages/mini-oxygen exec vitest run src/vite/plugin.test.ts src/vite/environment.test.ts src/vite/utils.test.ts --test-timeout=60000
pnpm --dir packages/mini-oxygen run build

Testing

Check this other branch to test these changes in the skeleton template. Test also without those changes to ensure it works without breaking changes.

Allow the Oxygen Vite plugin to work without Hydrogen registering all deployment defaults. The plugin now defaults the Vite build output to dist, infers an Oxygen compatibility date from the resolved @Shopify/hydrogen package when no date is registered, and falls back to 2026-04-01 for non-calver Hydrogen versions. Keep explicit compatibility dates registered by the Hydrogen plugin authoritative, and add focused coverage for default build options, inferred oxygen.json emission, explicit-date precedence, and graceful metadata failures. Co-authored-by: Codex <codex@openai.com> Assisted-By: devx/cfcff76e-c93f-4252-a696-0009d08d7009

Add Hydrogen deploy flags for explicit client assets and worker output directories, and resolve deploy directories from flags, Vite output, then dist fallbacks. Use the package build script via node --run build for custom output deployments and 0.0.0-preview Hydrogen versions so those projects do not go through the Hydrogen runBuild hook. Keep explicit --build-command values authoritative. Co-authored-by: Codex <codex@openai.com>

Prefer Vite's environment-specific SSR and client output directories when resolving deploy output paths, then fall back to the existing server-to-client naming convention. Expand the CLI changeset to describe Vite output detection and the node --run build fallback for standalone output deployments. Co-authored-by: Codex <codex@openai.com>

Stop forcing a dist build output from the Mini Oxygen Vite plugin, while keeping compatibility-date inference self-contained. Preserve configured worker entry module IDs for SSR build fallback, including virtual and package IDs, and prepend a clearer Mini Oxygen response when Vite cannot load the configured worker entry. Co-authored-by: Codex <codex@openai.com>

Move worker-specific resolve conditions out of the top-level Vite resolver so client modules keep normal browser conditions. Keep helper error text out of the dev worker entry runtime exports so Miniflare only sees the default handler. Co-authored-by: Codex <codex@openai.com>

Regenerate the OCLIF manifest so the deploy command exposes the new assets and worker directory flags plus the updated build-command description. Co-authored-by: Codex <codex@openai.com>

Keep the missing-entry message private to the worker entry and hardcode the expected text in the test instead of adding a shared helper module. Co-authored-by: Codex <codex@openai.com>

Remove the remaining missing-entry message constant and assert the literal text directly in worker entry tests. Co-authored-by: Codex <codex@openai.com>

Prevent the Mini Oxygen Vite plugin from writing oxygen.json during client builds so the metadata only lands with the server worker output. Update tests and the changeset accordingly. Co-authored-by: Codex <codex@openai.com>

Run vite preview through Mini Oxygen by creating a preview runtime from the built worker output, with previewEntry support and default server entry discovery. Move the shared Miniflare request conversion into Vite utilities and cover the preview output resolution paths in tests. Co-authored-by: OpenAI <noreply@openai.com>

Load Vite environment variables for standalone Mini Oxygen dev and preview when no env bindings are provided by plugin options or the Hydrogen CLI. Skip the fallback when env or envPromise is registered, preserving CLI-provided bindings. Co-authored-by: OpenAI <codex@openai.com>

shopify · 2026-06-25T15:44:31Z

Oxygen deployed a preview of your fd-standalone-oxygen-deployment branch. Details:

Storefront	Status	Preview link	Deployment details	Last update (UTC)
Skeleton (skeleton.hydrogen.shop)	✅ Successful (Logs)	Preview deployment	Inspect deployment	June 29, 202612:12 PM

Learn more about Hydrogen's GitHub integration.

Co-authored-by: OpenAI <codex@openai.com>

This reverts commit ae28577.

frandiox · 2026-06-25T17:01:57Z

+  return `${versionMatch[1]}-${String(month).padStart(2, '0')}-01`;
+}
+
+export function getHydrogenCompatibilityDate(root = process.cwd()) {


The original idea was put the unlikely compat date breaking changes behind Hydrogen's calver releases. We could also decouple it and just update mini-oxygen package once in a while, even if it's a major bump.

Some Vite-based tools finalize build.ssr after the early config hook, so env.isSsrBuild can be false even for the eventual SSR worker build. Use the resolved Vite config when deciding whether to emit oxygen.json, while keeping the early hook behavior for the build.ssr entry fallback. Add regression coverage for SSR builds that are only visible in configResolved. Co-authored-by: OpenAI <codex@openai.com>

frandiox · 2026-06-26T06:40:20Z

      },
      configResolved(resolvedConfig) {
        root = resolvedConfig.root;
+        isSsrBuild = Boolean(resolvedConfig.build.ssr);


Certain tools like Vinxi doesn't get env.isSsrBuild: true because Vite resolves that too early. Getting it from the configResolved seems to work better for these tools.

fredericoo

hard to tophat, seems like it works. would like clearer instructions, but it looks 100% backwards compat so we are fine

frandiox · 2026-06-29T10:19:30Z

hard to tophat, seems like it works. would like clearer instructions,

You need to use the changes in this other PR. From there, it's basically testing that pnpm run dev, pnpm run build, pnpm run preview and shopify hydrogen deploy --force works. You might need shopify hydrogen env pull first to get the proper env variables.

Why: custom Oxygen deployments may use the Hydrogen deploy command without installing @Shopify/hydrogen, so deployment metadata detection should not fail or resolve the CLI's own dependency by accident. Read the app-local @Shopify/hydrogen package.json directly, return undefined when it is missing or malformed, and type the package JSON read before using its version field. Co-authored-by: OpenAI <codex@openai.com>

Why: the workspace and Shopify CLI already require Node 22+, so the Hydrogen CLI package should not continue advertising Node 20 compatibility. Align the @shopify/cli-hydrogen engines field with the supported Node runtime range by requiring Node 22 or Node 24. Co-authored-by: OpenAI <codex@openai.com>

Why: custom Oxygen deployments should not fail when @Shopify/hydrogen metadata is unavailable, but apps that do install Hydrogen should still be read through Node package resolution instead of a hardcoded node_modules path. Keep the original require.resolve(..., {paths: [root]}) behavior, return undefined when resolution or package parsing fails, and guard the version field with the PackageJson type. Adjust the deploy test resolver so Vitest does not leak workspace Hydrogen into app-local resolution cases. Co-authored-by: OpenAI <codex@openai.com>

frandiox and others added 11 commits June 24, 2026 18:10

Update Hydrogen deploy CLI manifest

0a02211

Regenerate the OCLIF manifest so the deploy command exposes the new assets and worker directory flags plus the updated build-command description. Co-authored-by: Codex <codex@openai.com>

Inline worker entry error text

8fcd7f9

Keep the missing-entry message private to the worker entry and hardcode the expected text in the test instead of adding a shared helper module. Co-authored-by: Codex <codex@openai.com>

Inline missing worker entry message

d6f5d96

Remove the remaining missing-entry message constant and assert the literal text directly in worker entry tests. Co-authored-by: Codex <codex@openai.com>

Emit Oxygen metadata only for SSR builds

4fe97b4

Prevent the Mini Oxygen Vite plugin from writing oxygen.json during client builds so the metadata only lands with the server worker output. Update tests and the changeset accordingly. Co-authored-by: Codex <codex@openai.com>

frandiox requested a review from a team as a code owner June 25, 2026 15:43

temporary workaround

ae28577

Co-authored-by: OpenAI <codex@openai.com>

frandiox added the gsd:50917 label Jun 25, 2026

Revert "temporary workaround"

3bfa5bd

This reverts commit ae28577.

frandiox commented Jun 25, 2026

View reviewed changes

frandiox commented Jun 26, 2026

View reviewed changes

frandiox requested review from andguy95 and fredericoo June 26, 2026 06:40

frandiox mentioned this pull request Jun 26, 2026

templates/react-router: add standalone RR7 storefront template #3818

Merged

fredericoo approved these changes Jun 26, 2026

View reviewed changes

fredericoo reviewed Jun 26, 2026

View reviewed changes

Comment thread packages/cli/src/commands/hydrogen/deploy.ts Outdated

Comment thread packages/cli/src/commands/hydrogen/deploy.ts

frandiox and others added 2 commits June 29, 2026 20:53

frandiox force-pushed the fd-standalone-oxygen-deployment branch from 846c7e7 to 66a6a66 Compare June 29, 2026 11:55

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Make Oxygen deployment flows standalone#3819

Make Oxygen deployment flows standalone#3819
frandiox wants to merge 17 commits into
mainfrom
fd-standalone-oxygen-deployment

frandiox commented Jun 25, 2026 •

edited

Loading

Uh oh!

shopify Bot commented Jun 25, 2026 •

edited

Loading

Uh oh!

frandiox Jun 25, 2026

Uh oh!

frandiox Jun 26, 2026

Uh oh!

fredericoo left a comment

Uh oh!

Uh oh!

Uh oh!

frandiox commented Jun 29, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

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

Uh oh!

Summary

Validation

Testing

Uh oh!

shopify Bot commented Jun 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

frandiox Jun 25, 2026

Choose a reason for hiding this comment

Uh oh!

frandiox Jun 26, 2026

Choose a reason for hiding this comment

Uh oh!

fredericoo left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

frandiox commented Jun 29, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

frandiox commented Jun 25, 2026 •

edited

Loading

shopify Bot commented Jun 25, 2026 •

edited

Loading