Shopify Oxygen Deployment: Complete Hydrogen Hosting Guide (2026)

When Shopify introduced Hydrogen as its React-based storefront framework, one question immediately followed: where do you actually run it? Node.js servers, edge runtimes, and third-party platforms all work — but none of them integrate as tightly with Shopify's commerce APIs as the platform's own hosting layer. That layer is Shopify Oxygen deployment, a globally distributed edge runtime built specifically for Hydrogen storefronts. This article covers everything engineering teams need to know: architecture, requirements, deployment workflow, environment management, caching patterns, limitations, and cost — with real CLI commands and configuration examples throughout.

What Is Shopify Oxygen?

Shopify Oxygen is the managed oxygen edge hosting infrastructure that Shopify operates exclusively for Hydrogen storefronts. Rather than running your storefront on a traditional origin server in a single data center, Oxygen deploys worker instances to hundreds of edge locations worldwide via Cloudflare Workers — see the official Oxygen deployment documentation for the latest infrastructure details — the same V8-isolate runtime used by Cloudflare's own products.

Every request is served from the nearest edge point-of-presence to the shopper, cutting time-to-first-byte dramatically compared to centralized hosting. Because workers spin up in microseconds rather than milliseconds, cold-start latency — the bane of serverless containers — is effectively eliminated.

Core Technical Properties

• Runtime: V8 isolates (not Node.js). Your Hydrogen bundle runs in a ServiceWorker-compatible environment with the standard Web APIs: fetch, Request, Response, Headers, Cache, crypto, and URL.
• Global distribution: 300+ edge locations automatically; no region selection required.
• Automatic scaling: Horizontal scaling is handled entirely by the platform. There are no instance counts, auto-scaling groups, or capacity planning tasks.
• Zero-downtime deploys: Traffic is shifted to new worker versions atomically — rolling deploys without configuration.
• Native Storefront API proximity: Worker instances run in the same network fabric as Shopify's Storefront API, reducing round-trip latency for every data fetch.

Understanding this foundation matters before you configure a single environment variable. Oxygen is not a generic container host with a Shopify badge — it is a purpose-built runtime that imposes specific constraints while offering advantages no third-party host can replicate.

Oxygen vs Traditional Hosting for Hydrogen

Teams evaluating Shopify Oxygen hosting often compare it against Vercel, Fly.io, or self-managed infrastructure. The table below captures the most operationally relevant differences.

The key trade-off is constraint versus integration. Oxygen gives you the tightest Shopify integration and zero hosting overhead, in exchange for a strict worker execution model and GitHub-only source control support. Teams that need GitLab pipelines or custom Docker images will still reach for Vercel or Fly.io. Everyone else should default to Oxygen.

Shopify Oxygen Deployment Requirements

Before you can deploy Hydrogen to Oxygen, several prerequisites must be in place.

Shopify Plan

Oxygen is available on Shopify Advanced and Shopify Plus plans only. Basic and Grow plans do not include access. If you are on a lower tier you will need to either upgrade or host Hydrogen externally.

Hydrogen Framework Version

Your storefront must use Shopify Hydrogen — the official React framework built on Remix. Projects scaffolded with @shopify/create-hydrogen are automatically configured for Oxygen's worker environment. Raw Remix or Next.js apps require significant adaptation and are not officially supported on Oxygen.

Shopify CLI Version

You need Shopify CLI 3.x or later, which bundles the hydrogen plugin:

npm install -g @shopify/cli @shopify/theme
shopify version          # should output 3.x.x or higher

GitHub Repository

Oxygen connects exclusively to GitHub. Your Hydrogen project must be in a GitHub repository (public or private) that your Shopify Partner or store account has permission to access. GitLab, Bitbucket, and bare-git remotes are not supported at this time.

Storefront API Credentials

You will need a Storefront API access token and your store's public domain. These become environment variables injected at build time — they are not pulled automatically from your Shopify admin.

Step-by-Step Shopify Oxygen Deployment

1. Create a Hydrogen Storefront

Scaffold a new Hydrogen project using the official CLI. The demo-store template includes a working storefront connected to Shopify's demo catalog — useful for validating your Oxygen setup before wiring in real store data.

npx @shopify/create-hydrogen@latest my-storefront
cd my-storefront
npm install

Choose the Oxygen deployment target when prompted. The scaffolder adjusts vite.config.ts and the server entry point to target the Cloudflare Workers runtime instead of Node.js.

2. Link a GitHub Repository

Push your project to GitHub, then link it to a Shopify storefront from the Shopify admin under Online Store → Hydrogen, or via the CLI:

shopify hydrogen link

This command authenticates with your Shopify store, lists available Hydrogen storefronts, and writes a .shopify/project.toml file that stores the association. This file should be committed to your repository — it is not sensitive.

3. Configure Environment Variables

Push your required environment variables to Oxygen's secret store before the first production deploy:

shopify hydrogen env push

This reads your local .env file and uploads each variable to the Oxygen environment associated with your linked storefront. Variables are encrypted at rest. For branch-specific overrides, use the Shopify admin's Environment variables panel.

4. Deploy via CLI

To trigger a production Shopify Oxygen deployment from your local machine or a CI pipeline, run:

shopify hydrogen deploy --shop=your-store.myshopify.com

The CLI bundles your Hydrogen app using Vite, uploads the compressed worker bundle to Oxygen, and promotes it to live traffic atomically. You will see a deployment URL in the output within 30–90 seconds depending on bundle size.

For CI pipelines, pass credentials via environment variables rather than interactive authentication:

# In GitHub Actions
- name: Deploy to Oxygen
  env:
    SHOPIFY_CLI_PARTNERS_TOKEN: ${{ secrets.SHOPIFY_CLI_PARTNERS_TOKEN }}
  run: shopify hydrogen deploy --shop=your-store.myshopify.com

5. Connect a Custom Domain

After your first successful Shopify Oxygen deployment, navigate to Online Store → Domains in your Shopify admin. Add your custom domain and point its DNS CNAME record to the Oxygen-provided hostname (typically custom.myshopify.com or a store-specific edge address shown in the admin). TLS certificates are provisioned and renewed automatically — no Certbot, no ACM, no manual renewal process.

Environment Variables and Secrets Management

Oxygen distinguishes between two categories of variables, and the distinction is enforced at the framework level via Hydrogen's createStorefrontClient and createCustomerAccountClient utilities.

Public Variables (PUBLIC_ prefix)

Variables prefixed with PUBLIC_ are bundled into the client-side JavaScript and exposed to the browser. Use these only for non-sensitive data: your public Storefront API token, store domain, and feature flags.

PUBLIC_STORE_DOMAIN=your-store.myshopify.com
PUBLIC_STOREFRONT_API_TOKEN=abc123def456
PUBLIC_STOREFRONT_API_VERSION=2024-04

Private Variables (no prefix)

Variables without the PUBLIC_ prefix are available only inside worker request handlers — they are never serialized to the client bundle. Use these for Customer Account API secrets, third-party service keys, and anything that must not be exposed in browser JavaScript.

PRIVATE_STOREFRONT_API_TOKEN=secret_xyz
CUSTOMER_ACCOUNT_API_CLIENT_ID=client_id_here
CUSTOMER_ACCOUNT_API_URL=https://shopify.com/authentication/...

Accessing Variables in Hydrogen

// server.ts
export default {
  async fetch(
    request: Request,
    env: Env,
    executionContext: ExecutionContext
  ): Promise {
    const {storefront} = createStorefrontClient({
      cache,
      waitUntil: executionContext.waitUntil.bind(executionContext),
      publicStorefrontToken: env.PUBLIC_STOREFRONT_API_TOKEN,
      privateStorefrontToken: env.PRIVATE_STOREFRONT_API_TOKEN,
      storeDomain: env.PUBLIC_STORE_DOMAIN,
    });
  }
};

The env object is Cloudflare Workers' native binding mechanism — Oxygen populates it from your Oxygen secret store at request time, not at bundle time. This means you can rotate secrets without redeploying your worker bundle.

Preview Deployments and Branch Previews

One of the most operationally valuable features of Shopify Oxygen hosting is automatic preview environments for every branch and pull request. When you push to any branch in your linked GitHub repository, Oxygen builds a worker bundle and deploys it to an isolated preview URL of the form:

https://..oxygen.shopifypreview.com

Preview environments are ephemeral — they persist as long as the branch exists and are torn down automatically when branches are deleted or merged. Each preview runs against the same Shopify store as production unless you override the storefront credentials in Oxygen's branch-specific environment variable panel.

Practical Workflow Benefits

• QA teams and stakeholders can review feature branches without any DevOps involvement.
• Pull request links can be posted automatically using GitHub Actions with the Oxygen deploy output URL.
• A/B testing infrastructure can route a percentage of traffic to a named preview deployment without full promotion.
• Breaking changes in Storefront API versions can be validated on a branch before they affect production shoppers.

For teams currently evaluating whether to invest in Shopify Hydrogen development services, the preview deployment workflow alone significantly reduces the coordination overhead that slows down headless storefront projects.

Caching Strategies on Oxygen

Caching in a worker environment works differently from caching on a traditional CDN or reverse proxy. Oxygen exposes the standard Cache API (caches.default) and integrates with Hydrogen's built-in caching utilities. Getting caching right is the primary lever for performance in a Shopify Oxygen deployment.

Cache-Control Headers

Responses returned from your worker can include standard Cache-Control headers. Oxygen's edge layer respects s-maxage for shared cache TTLs and max-age for client-side caching.

// In a Hydrogen loader
export async function loader({context}: LoaderFunctionArgs) {
  const {storefront} = context;
  const data = await storefront.query(PRODUCTS_QUERY, {
    cache: storefront.CacheCustom({
      mode: 'public',
      maxAge: 60,          // revalidate after 60 seconds
      staleWhileRevalidate: 600  // serve stale for up to 10 minutes
    }),
  });
  return json(data);
}

Stale-While-Revalidate Patterns

The stale-while-revalidate directive is particularly important for commerce storefronts where product data changes infrequently but must feel instant. Hydrogen's storefront.CacheLong(), storefront.CacheShort(), and storefront.CacheCustom() presets all support SWR semantics:

• CacheShort() — 1 second max-age, 9 seconds stale-while-revalidate. Good for cart-adjacent data.
• CacheLong() — 3600 seconds max-age, 82800 seconds stale-while-revalidate. Good for navigation menus and static content.
• CacheCustom() — Full control. Use for product pages, collection pages, and anything with known invalidation patterns.

Sub-Request Caching

Worker subrequests to the Storefront API are individually cacheable. Hydrogen's storefront.query() wraps every GraphQL call with configurable caching at the subrequest level, meaning a single page render can serve some data from cache while fetching other data fresh — all within a single worker invocation.

Monitoring and Debugging Oxygen Deployments

Observability for worker deployments requires different tooling than traditional server monitoring. Oxygen provides several native mechanisms, but teams building production storefronts will want to supplement them.

Shopify Admin Deployment Logs

The Online Store → Hydrogen section of the Shopify admin lists all deployments with status, deploy time, and a truncated activity log. Build errors surface here first — this is where you verify that a bundle compiled and uploaded successfully.

Runtime Logs via CLI

Oxygen streams runtime logs (console output, unhandled exceptions) via the Shopify CLI:

shopify hydrogen debug --shop=your-store.myshopify.com

This command tails logs from the production worker in real time. For preview environments, pass the --environment flag with the branch name.

Real-User Monitoring

Oxygen does not currently expose a native real-user monitoring (RUM) dashboard. For Core Web Vitals and field data, inject a third-party RUM snippet (Datadog RUM, Sentry Performance, or Google's web-vitals library) in your Hydrogen root layout. Because workers run at the edge, server-side timings will be excellent by default — most RUM investment should focus on client-side JavaScript performance and LCP image loading.

Error Tracking

Sentry works well in V8 isolate environments. Initialize it in your worker entry point before the request handler, using the @sentry/cloudflare package which is compatible with Oxygen's runtime:

import * as Sentry from '@sentry/cloudflare';

Sentry.init({
  dsn: env.SENTRY_DSN,
  tracesSampleRate: 0.1,
});

Shopify Oxygen Deployment Limitations

No platform is without constraints. Being explicit about Oxygen's limitations up front prevents architectural surprises mid-project. Teams comparing Oxygen to alternatives should weigh these against Oxygen's integration benefits — for further context on how this compares to Liquid-based architectures, see this overview of Shopify Hydrogen vs Liquid.

Worker Bundle Size: 2 MB Compressed

Your compiled Hydrogen worker bundle — all server-side JavaScript, dependencies, and assets bundled into the worker entry point — must be under 2 MB when compressed. This is the single constraint most likely to cause problems on complex storefronts. Common approaches to staying under the limit:

• Audit your server-side imports. Dependencies that load on every request inflate the bundle even if used rarely.
• Move heavy server-side libraries to external API calls where possible.
• Use Vite's build.rollupOptions.external to exclude packages available as native Web APIs (node:crypto substitutes, etc.).
• Run shopify hydrogen build --bundle-stats to identify the largest contributors to bundle size.

CPU Time: 50 ms Wall-Clock, 500 ms Burst

Each worker invocation has a 50 ms CPU time budget in normal operation, with a burst allowance up to 500 ms. CPU time excludes time spent waiting on I/O (Storefront API calls, external fetches) — those are effectively free from a CPU budget perspective. However, CPU-intensive server-side operations such as large data transformations, complex sorting, or server-side template rendering over large datasets will hit this limit.

No Persistent Storage

Workers are stateless. There is no in-memory session store, no local file system, and no persistent connection to a database. All state must live in Shopify (cart, customer, metafields), in cookies, or in external services accessed via fetch.

No WebSocket Support

Long-lived WebSocket connections are not supported in the Oxygen worker runtime. Real-time features (live inventory, streaming AI responses) require either polling via fetch or an external service that the client connects to directly.

GitHub-Only Source Control

As noted in the requirements section, Oxygen's CI/CD integration is GitHub-exclusive. This is a firm platform limitation, not a configuration gap.

Cost: Is Oxygen Really Free?

Oxygen is included in Shopify Advanced and Plus plans at no additional hosting charge — there is no separate line item for edge compute, bandwidth, or requests. For most production storefronts, this means the effective cost of Shopify Oxygen deployment is zero beyond the plan subscription.

What Is Included

• Unlimited worker deployments (production and preview)
• Global edge distribution across 300+ locations
• TLS termination and certificate management
• Custom domain support
• Environment variable storage (encrypted)
• Deployment logs and CLI tooling

Potential Additional Costs

Shopify does not publish an overage pricing schedule for Oxygen as of early 2026. Extremely high-traffic storefronts (tens of millions of monthly requests) should verify current entitlements with their Shopify Plus account manager before assuming unlimited included usage. Bandwidth for media assets served from Shopify's CDN is governed by standard Shopify plan limits, not Oxygen-specific limits.

Compared to self-managed infrastructure — where a globally distributed Cloudflare Workers deployment with similar scale would cost several hundred dollars per month in worker invocations and bandwidth — Oxygen represents significant infrastructure savings for teams on eligible plans. This economic advantage compounds when you account for the operational overhead eliminated by not managing worker deployments, TLS certificates, domain routing, and scaling configurations independently. Teams exploring this path should consider the broader case for building a headless Shopify store to understand the full cost-benefit picture.

Conclusion

Shopify Oxygen deployment is the most operationally efficient path to production for teams building Hydrogen storefronts on Shopify Advanced or Plus. Its Cloudflare Workers foundation delivers genuine global edge performance with zero infrastructure management overhead. The bundle size and CPU time constraints are real engineering considerations, not dealbreakers — teams that understand them early design around them successfully. The GitHub-only CI/CD integration is the most significant workflow limitation for organizations standardized on other source control platforms.

For most CTOs and engineering leads evaluating Hydrogen, the decision framework is straightforward: if you are on Advanced or Plus and your team uses GitHub, deploy Hydrogen to Oxygen and eliminate an entire infrastructure layer from your operational responsibility. If you need GitLab, Bitbucket, or full Node.js runtime access, evaluate Vercel Edge or Fly.io against your specific workload.

If your team needs expert guidance architecting a Hydrogen storefront for Shopify Oxygen hosting — from initial scaffold to production deployment, caching strategy, and performance optimization — MGroup's engineers specialize in exactly this stack. Reach out to discuss your project requirements.