How We Built Oxygen: Hydrogen’s Counterpart for Hosting Custom Storefronts

Summary

Oxygen is Shopify’s hosting counterpart for Hydrogen custom storefronts, designed to provide globally available, fast storefronts with secure Shopify integration without additional third-party hosting costs. Its architecture combines GitHub and GitHub Actions with Cloudflare Workers and edge distribution, Shopify CDN, Admin API, Identity and Access Management, and Oxygen-scoped developer tooling and observability. Requests pass through a Gateway Worker, which validates authorization for the shop and storefront version before using Cloudflare’s Dynamic Dispatch API to route traffic to a Storefront Worker running Hydrogen code. Rather than build proprietary infrastructure, Shopify reused Cloudflare’s worker platform to reduce upfront complexity, scale, and security risks, while its observability stack uses Grafana, Cortex, Loki, and Tempo. Oxygen is used in production by Allbirds, Shopify Supply, Shopify Hardware, and Denim Tears, and is generally available to Plus merchants.

Context

Shopify built Oxygen to make hosting Hydrogen custom storefronts easy and seamless while providing tight integration with Shopify. The stated goals were high availability, fast performance from anywhere in the world, resilience under high-volume traffic, secure access controls, and a frictionless merchant experience without requiring merchants to configure separate third-party hosting tools.

Approach / What changed

Oxygen bundles GitHub, GitHub Actions, Cloudflare Workers and edge distribution, Shopify CDN, Shopify Admin API, Shopify Identity and Access Management, and Oxygen-scoped services. Cloudflare’s worker infrastructure handles runtime and distribution; a Gateway Worker validates shop and storefront-version authorization before dispatching requests to a Hydrogen Storefront Worker. A Trace Worker forwards logs and metrics into Grafana, Loki, Cortex, and Tempo, surfaced through the Hydrogen channel.

Takeaways

• Oxygen uses Cloudflare’s worker infrastructure instead of Shopify’s initially explored proprietary infrastructure, reducing upfront infrastructure complexity, scale considerations, and security risks.
• A Gateway Worker checks authorization for both the shop and the requested storefront version before routing requests to the Hydrogen-based Storefront Worker through Cloudflare’s Dynamic Dispatch API.
• Oxygen’s observability stack uses Grafana for dashboards and alerting, Cortex for metrics, Loki for logging, and Tempo for tracing, with data surfaced in the Hydrogen channel.

Related reading