Deploying a Hydrogen App to Shopify’s Oxygen Hosting

Introduction

Building a headless storefront with Hydrogen gives you powerful React-based commerce primitives, but to deliver that experience at scale you need fast, reliable hosting. Shopify’s Oxygen Hosting is purpose-built for Hydrogen apps: it provides a global edge network, automatic SSL, instant cache invalidation, and built-in support for Storefront API credentials—so you can deploy in minutes without managing servers. In this guide, we’ll take you from a local Hydrogen project to a production-ready deployment on Oxygen. You’ll learn how to prepare your project, configure environment variables, connect your Git repo, run the Oxygen CLI commands, and implement best practices for performance, security, and seamless updates. By the end, your storefront will be live on a Shopify-hosted CDN, ready to delight customers worldwide.

1. Understanding Shopify Oxygen Hosting

Before diving in, let’s clarify what Oxygen offers and why it’s ideal for Hydrogen apps.

• Edge-first Infrastructure
  Your app runs on Shopify’s global CDN network, serving content from locations closest to end users for sub-100ms response times.
• Seamless API Integration
  Built-in support for Storefront API tokens and Shopify Domains means zero manual proxy setups.
• Instant Cache Invalidation
  Push a new commit and Oxygen automatically purges stale assets and data caches.
• Automatic SSL & Custom Domains
  Out of the box, your .myshopify.com subdomain is secured with HTTPS; adding custom domains is just one CLI flag away.
• Zero Server Management
  No servers to patch, monitor, or scale—Shopify handles runtime updates and DDoS protection for you.

Analogy: Think of Oxygen as an autopilot for your Hydrogen app—once you configure your flight plan (project), the platform takes off, handles turbulence (traffic spikes), and lands you safely on the edge network runway.

2. Prerequisites

Ensure you have the following before starting:

1. Hydrogen Project
   A working Hydrogen storefront scaffolded via npm create @shopify/hydrogen.
2. Shopify Store
   An active Shopify store to generate your Storefront API token.
3. Git Repository
   Your project code checked into a Git repository (GitHub, GitLab, or Bitbucket).
4. Oxygen CLI
   Installed globally via npm: bashCopyEditnpm install --location=global @shopify/oxygen
5. Node.js & Git
   Node v16+ and Git installed on your local machine.

3. Configuring Your Hydrogen App for Oxygen

3.1 Verify package.json Scripts

Hydrogen’s default scaffold includes a start and build script. Oxygen expects a build that outputs to ./build:

jsonCopyEdit{
  "scripts": {
    "dev": "hydrogen dev",
    "build": "hydrogen build",
    "start": "hydrogen start"
  }
}

• hydrogen build compiles and bundles your server and client code into build/.

3.2 Add an oxygen.config.js (Optional)

For advanced control (custom headers, redirects), create oxygen.config.js in your project root:

jsCopyEditmodule.exports = {
  headers: [
    {
      source: "/(.*)",
      headers: [
        { key: "Cache-Control", value: "public, max-age=0, must-revalidate" }
      ],
    },
  ],
  redirects: [
    { source: "/old-path", destination: "/new-path", permanent: true },
  ],
};

4. Setting Up Environment Variables

Your storefront needs two critical variables:

• SHOPIFY_STORE_DOMAIN
• SHOPIFY_STOREFRONT_API_TOKEN

4.1 Local .env File

Create a .env in your project root (gitignored by default):

envCopyEditSHOPIFY_STORE_DOMAIN=your-shop.myshopify.com
SHOPIFY_STOREFRONT_API_TOKEN=pk_live_yourPublicToken

4.2 Committing to Oxygen

You’ll push these values to Oxygen’s secrets store rather than your repo:

bashCopyEditoxygen secret set SHOPIFY_STORE_DOMAIN=your-shop.myshopify.com
oxygen secret set SHOPIFY_STOREFRONT_API_TOKEN=pk_live_yourPublicToken

This keeps sensitive data out of version control while providing runtime access.

5. Connecting Your Git Repository

Oxygen supports GitHub, GitLab, and Bitbucket. Linking your repo enables continuous deployments on push.

1. Authenticate bashCopyEditoxygen login This opens a browser to authorize your Git provider.
2. Create an Oxygen Project bashCopyEditoxygen project create
   • Select your Git provider.
   • Choose the repo and branch (typically main or master).
   • Name your project (e.g., hydrogen-storefront).

Once linked, Oxygen generates a webhook: every push to the configured branch triggers a new build and deploy.

6. First Deployment

With repo linked and secrets set, run:

bashCopyEditoxygen deploy

• Build Stage: Runs npm install and npm run build.
• Deploy Stage: Uploads the build/ directory to Oxygen’s edge network.

On success, you’ll receive a URL:

arduinoCopyEdit✔ Deployment complete!
🚀 View your app at: https://hydrogen-storefront.oxygen.myshopify.com

Share or bookmark this URL, or point a custom domain to it

7. Adding a Custom Domain

To use store.yourdomain.com instead of the .oxygen.myshopify.com subdomain:

1. Add Domain in Oxygen: bashCopyEditoxygen domain add store.yourdomain.com
2. DNS Configuration:
   • Create a CNAME record: objectivecCopyEditstore CNAME hydrogen-storefront.oxygen.myshopify.com
   • It may take up to 30 minutes to propagate.
3. Verify SSL:
   Oxygen automatically issues an SSL certificate via Let’s Encrypt. Check status: bashCopyEditoxygen domain list

8. Monitoring, Rollbacks, and Logs

8.1 Deployment History & Rollbacks

bashCopyEditoxygen deploy:list

Shows past deployments. To roll back:

bashCopyEditoxygen deploy:rollback <deployment-id>

8.2 Real-Time Logs

Stream logs during build or runtime:

bashCopyEditoxygen logs --follow

Useful for catching build errors, runtime exceptions, or console debugging.

9. Best Practices & Optimization

9.1 Incremental Static Regeneration (ISR)

Configure your Next.js/Hydrogen pages with revalidate to keep content fresh without full rebuilds:

jsCopyEditexport async function getStaticProps() {
  const data = await shopifyQuery(PRODUCTS_QUERY);
  return { props: { products: data.products }, revalidate: 60 };
}

9.2 Asset Compression & Caching

• GZIP/Brotli: Oxygen automatically compresses JS/CSS assets.
• Cache-Control Headers: Use oxygen.config.js or HTTP header APIs to extend client-side caching for static assets: jsCopyEditheaders: [ { source: "/assets/(.*)", headers: [{ key: "Cache-Control", value: "public, max-age=31536000, immutable" }], }, ],

9.3 Build Size Analysis

Install Webpack Bundle Analyzer:

bashCopyEditnpm install --save-dev @next/bundle-analyzer

And add to next.config.js:

jsCopyEditconst withBundleAnalyzer = require('@next/bundle-analyzer')({ enabled: true });
module.exports = withBundleAnalyzer({});

Run ANALYZE=true npm run build to view your bundle composition.

10. Updating and Redeploying

10.1 Feature Branch Previews

Create a new branch and push to trigger an isolated preview:

bashCopyEditgit checkout -b feature/new-cart
git push origin feature/new-cart

Oxygen auto-generates a unique preview URL for QA and stakeholder reviews.

10.2 Merge and Deploy

Once approved, merge into your main branch. The webhook triggers a full production deploy automatically.

Conclusion

Deploying your Hydrogen storefront to Shopify’s Oxygen Hosting transforms your local React app into a globally distributed, edge-powered storefront with zero server management. By following this guide—configuring your build, managing secrets, linking your Git repo, and leveraging Oxygen’s CLI—you’ll achieve fast deployments, automatic SSL, instant cache invalidation, and robust monitoring. Embrace Oxygen to focus on crafting delightful user experiences, knowing that your site scales seamlessly and remains secure. Ready to go live? Run that first oxygen deploy and watch your app propagate to the edge in seconds!