npm / @shopify/mini-oxygen
@shopify/mini-oxygen
What changed in @shopify/mini-oxygen 2 to 4, from its official release notes, upgrade guides and advisories. Sources checked 2026-11-15.
10 breaking5 new APIs and options8 behavior and defaults2 tooling10 fixes and other
See which of these apply to your code, ranked, in your agent:
npx @unstale/cli init@shopify/mini-oxygen 427 changes
Breaking changes 5
Local development now runs the requested compatibility date, or the newest date supported by the bundled runtime and prints a warning if the requested date is unsupported.
MiniOxygen re-exports Response from Miniflare; it is now an undici 7 class instead of an undici 5 class.
The file is emitted only during SSR builds.
The skeleton template no longer needs the vite-tsconfig-paths plugin because Vite 8 supports resolve.tsconfigPaths natively.
The Customer Account API development flag is stable and ready for production use; it enables tunneling for local OAuth development.
New APIs and options 3
An optional override lets developers specify custom worker output paths for preview.
MiniOxygen adds support for the Oxygen compatibility date parameter.
MiniOxygen adds support for Oxygen compatibility flags.
Behavior and default changes 7
MiniOxygen re-exports fetch from Miniflare, now using undici 7 instead of undici 5.
MiniOxygen re-exports Request from Miniflare; it is now an undici 7 class instead of an undici 5 class.
The Oxygen Vite plugin infers a compatibility date from the resolved Hydrogen package when one is not provided.
The Oxygen Vite plugin loads Vite environment variables as Mini Oxygen bindings when plugin options or the Hydrogen CLI provide no env bindings.
Worker-specific resolve conditions apply only to the SSR worker environment, leaving browser/client modules on Vite's normal client conditions.
New Hydrogen projects created with npm create @shopify/hydrogen will default to Vite 8.
This environment variable enables the stable Customer Account API development flag.
Tooling 2
The command can run the built Oxygen worker in Mini Oxygen.
Mini Oxygen supports Vite 7 and Vite 8 while remaining backwards-compatible with Vite 5+.
Fixes and other changes 10
The oxygen() Vite plugin now writes oxygen.json in builds using the Vite Environment API, preventing Oxygen from using its fallback compatibility date.
Local requests now include the traceparent header, matching the trace context Oxygen sets in production.
A failed runtime start fails the current request instead of stopping the dev server, and the next request retries.
When the Vite dev server runs over HTTPS, the worker receives a request URL with the https: scheme, so origin-dependent code sees the correct origin during local HTTPS development.
MiniOxygen's Vite request conversion now supports HTTP/2 requests.
Improves the reliability of local debugger connections.
The plugin forwards the top-level Vite setting to the custom SSR environment so tsconfig path aliases resolve at runtime.
Fixed defer and streaming in development and preview.
External redirects are returned instead of followed internally, allowing the browser to handle OAuth/PKCE flows.
Fixed the method for proper multi-cookie support.
@shopify/mini-oxygen 33 changes
Breaking changes 1
The default runtime exported from the package is now based on workerd.
New APIs and options 2
The previous Node.js sandbox runtime is available from this export.
A Vite plugin integrates Vite with MiniOxygen by running application code within a worker.
@shopify/mini-oxygen 25 changes
Breaking changes 4
Support for the JSON based configuration file is dropped.
The oxygen-gen-config command no longer exists.
Mini Oxygen can no longer be used in a standalone fashion.
The preview function is renamed to startServer, which is now a named export.
Behavior and default changes 1
Mini Oxygen is now built as an ESM module.