Skip to content
Back to Deployment

Deploying Shopify Hydrogen

Shopify's React storefront framework with Oxygen runtime, deploy to Shopify Oxygen or Node.

PlatformsAdvanced

Why

Hydrogen is Shopify's headless storefront framework built on Remix with Storefront API integration. Oxygen is its global edge runtime optimized for e-commerce with cached product data.

Platform-as-a-Service adoption grew 24% in 2024 as teams shift from VM management to git-push deploys. the cloud infrastructure market reached $330B in 2024, growing 22% year-over-year (Synergy Research), and PaaS layers capture the majority of new workloads.

When

Use Hydrogen for Shopify-backed storefronts needing custom UX and edge performance. Avoid if not on Shopify — use Remix/Next directly.

How

1. Build — npm run build produces dist/ 2. Oxygen — npx shopify hydrogen deploy, runs on Shopify's edge 3. Node — npm run build && node dist/server.js 4. Storefront API — set PUBLIC_STOREFRONT_API_TOKEN 5. Caching — Hydrogen caches product data at edge automatically

Example

// hydrogen.config.ts import { defineConfig } from "@shopify/hydrogen/config"; export default defineConfig({ shopify: { storeDomain: "https://mystore.myshopify.com", storefrontToken: process.env.PUBLIC_STOREFRONT_API_TOKEN }, }); // Deploy: npx shopify hydrogen deploy

Common Problems

  • ⚠Storefront API token missing — 401 on product queries
  • ⚠Oxygen deploy fails on custom server — Oxygen only supports Hydrogen's server entry
  • ⚠Configuration drift between environments — use infrastructure-as-code (Terraform/Pulumi) to keep dev/staging/prod identical

Best Practices

  • ✓Use Oxygen for production — global edge with Shopify-optimized caching
  • ✓Cache product collections with createWithCache for sub-100ms loads
  • ✓Set up health checks and graceful shutdown — handle SIGTERM to drain in-flight requests before exit

FAQ