Complete Oxygen Deployment Guide for Hydrogen
A lot of teams can build a Hydrogen storefront locally but struggle when deploying to production. This guide gives you the practical deployment flow, common errors, and launch checks to avoid broken releases.
Oxygen is Shopify's runtime for Hydrogen storefronts. It is designed to host storefront workloads close to Shopify commerce services and reduce custom infrastructure overhead.
Pre-Deployment Checklist
- Storefront API token created with correct permissions.
- Environment variables documented for all environments.
- Production build passes without warnings that affect runtime.
- Error logging and basic monitoring prepared before launch.
Step-by-Step Deployment Workflow
- Prepare your production branch: lock critical dependencies and confirm the current release candidate.
- Connect repository in Shopify: ensure the right store and branch are mapped.
- Set environment variables: API keys, domain values, and any external integration secrets.
- Trigger deployment: push to the production branch and watch deployment logs end to end.
- Run smoke tests: homepage, collection pages, PDP, cart, checkout redirect, and 404 pages.
Most Common Oxygen Deployment Problems
Missing or wrong environment variables
Symptoms include failed API requests, empty product grids, or cart actions not persisting. Always validate variable names and environment scope.
Route mismatches after slug changes
If handles or route rules changed during development, production can return unexpected 404 pages. Keep redirects and path mapping documented in each release.
Caching not aligned with catalog changes
Over-aggressive caching can show outdated prices or inventory. Define cache strategy by page type and expected data volatility.
Production Launch Validation
- Validate metadata and canonical tags on top pages.
- Confirm structured data is present and valid.
- Test cart to checkout flow on desktop and mobile.
- Check analytics and conversion tracking events.
- Verify sitemap contains newly published pages.
If you need technical SEO hardening after launch, follow this guide: Shopify Hydrogen SEO checklist.
Official Docs for Reference
Review the official Shopify docs for platform details: Hydrogen documentation and Oxygen documentation.