How to Deploy a Hydrogen Storefront on Shopify Oxygen

Hydrogen is Shopify's React framework for building custom (headless) storefronts, and Oxygen is Shopify's hosting built to run them. To deploy, you build your Hydrogen app, connect the store, and push to Oxygen, which serves the storefront on Shopify's global edge network at no extra hosting cost on paid plans. Headless is worth it when you need design or performance a Liquid theme cannot deliver. It is usually the wrong call for a standard catalog store, where a well-built theme ships faster and costs less to maintain.

Key Facts

• Hydrogen is Shopify's React-based framework for headless storefronts, built on React Router; Oxygen is the matching Shopify hosting.
• Oxygen serves storefronts from a global edge network and is included at no extra charge on paid Shopify plans, so there is no separate hosting bill to manage.
• Headless pays off for complex, content-heavy, or performance-critical builds, not for standard catalog stores.
• The main cost of going headless is ongoing engineering: you now own the front end that a theme used to handle for you.

What Hydrogen and Oxygen Actually Are

Hydrogen is a set of components, utilities, and CLI tooling on top of React Router, preconfigured for Shopify: API clients for the Storefront and Customer Account APIs come wired in, and common commerce components ship out of the box. Oxygen is Shopify's serverless hosting platform, a worker-based JavaScript runtime that deploys those apps to Shopify's edge network and handles environments, environment variables, caching, and CDN integration. Together they are Shopify's recommended stack for headless commerce.

What Oxygen Changes for a Headless Build

The historic downside of headless was operational: you built a custom storefront, then had to host, scale, and secure it yourself on a third-party platform. Oxygen removes that piece by hosting the Hydrogen app on Shopify's own edge network, tied to the store. You still own the front-end code and its upkeep, but you no longer run separate hosting infrastructure, which is what made earlier headless projects expensive to keep alive.

How to Deploy: From Empty Folder to Live Storefront

The full path is five steps, and Shopify's getting started guide covers each in detail. In practice a first deployment takes under an hour; it is the storefront you build afterwards that takes the time.

1. 1Install the Hydrogen sales channel from the Shopify App Store. It manages Oxygen deployments, environments, and API credentials.
2. 2Scaffold the app: npm create @shopify/hydrogen@latest generates a preconfigured React Router project. (Or create the storefront inside the Hydrogen channel and let Shopify scaffold a GitHub repo for you.)
3. 3Link it to your store: npx shopify hydrogen link connects the project to a storefront, and npx shopify hydrogen env pull fills your local .env with the store's API credentials.
4. 4Verify locally: npm run dev runs the app in a local emulation of the Oxygen worker runtime, showing your real catalog.
5. 5Deploy: npx shopify hydrogen deploy builds the app and pushes it to an Oxygen environment, returning a preview URL. For continuous deployment, connect the GitHub repo in the Hydrogen channel and merge the workflow PR it opens - after that, every push gets a preview deployment and production deploys from your main branch.

Two operational notes worth knowing before you commit. First, Oxygen has real platform limits - workers are capped at 10 MB, 128 MB of memory, and 30 seconds of CPU time per request - which are generous for a storefront but matter if you plan heavy server-side work. Second, Oxygen does not support proxies in front of your deployment, so if your architecture assumes one (for example, an existing reverse proxy handling multiple subdomains), plan around it.

When Headless Is the Right Call (and When It Is Not)

Go headless when a Liquid theme genuinely blocks you: a bespoke design system, content-driven pages a theme cannot structure, integrations that need a custom front end, or performance targets a theme cannot hit. Stay on a Liquid theme when the store is a fairly standard catalog and speed to launch and low maintenance matter more than front-end freedom. The deciding question is not "is headless better" but "does this specific store need what only headless provides." We cover that decision in depth in our guide on when to go headless.

The Byteex Headless Readiness Score

Five checks Byteex runs before recommending a headless build. If a store does not clear at least three, a Liquid theme is usually the better investment.

Headless vs Liquid Theme: A Quick Decision Guide

• Standard catalog, speed to launch matters: Liquid theme. You will ship in weeks and an agency or in-house team can maintain it cheaply.
• Bespoke design system or content-heavy storefront: Hydrogen on Oxygen. This is exactly the case the stack was built for.
• Hard performance targets the current theme cannot hit: Hydrogen on Oxygen, but only after confirming the theme itself is the bottleneck rather than apps and scripts.
• Low conversion rate on an existing theme: fix conversion first. Going headless does not fix a conversion problem by itself, and a re-platform delays the work that would.
• No dedicated engineering capacity: Liquid theme, regardless of how strong the design ambitions are. A custom front end without an owner degrades fast.

Guidance based on Byteex Shopify build and headless engagements (anonymized).

Work with Byteex

Not sure whether your store actually needs headless? A Byteex engineer can run the Headless Readiness Score on your build and give you a straight answer before you commit budget. Book a discovery call.