Deploying Hydrogen on Shopify Oxygen is not uploading code to a server. Define build, environment variables, Storefront API access, domains, cache, logs, preview, rollback, and market paths. Edge execution may reduce latency for some requests, but speed, SEO, and stability need real-page and real-traffic evidence.
Version boundary (2026-10): the current Hydrogen documentation describes a composable commerce toolkit; the selected framework owns routing, rendering, data loading, and builds. Use legacy documentation for 2026-04 and earlier versions. For an older React Router project, follow the migration guide: that path uses the application’s Vite/React Router development and build flow rather than copying legacy shopify hydrogen dev, shopify hydrogen build, or the hydrogen() Vite plugin configuration. This is not a universal command replacement table for every framework.
Deployment and cache boundaries
Separate development, preview, and production and never put customer or payment secrets in the frontend. Define cache lifetime and invalidation for product, stock, price, and market. After release inspect build log, error pages, redirects, canonical, structured data, and checkout. Prepare fallback for API timeout, build failure, stale cache, and vendor outage.
| Layer | Define | Acceptance |
|---|---|---|
| Build | Version, dependency, environment | Build log |
| Data | API access, cache, invalidation | API and timestamp |
| Page | Render, URL, markup | Crawl sample |
| Operations | Monitor, rollback, alert | Drill record |
Oxygen environment variables are captured with an immutable deployment. Changing them requires a new deployment, and rolling back restores the variables attached to the older deployment. The current environment documentation also distinguishes private previews, public environments, and plan conditions. Record access permissions, the deployed version, and its variable version; a working preview does not establish that production has the same configuration.
Review markets and caches together. Under the Markets guide, the application resolves country and language server-side and passes consistent context to queries and the page; Hydrogen does not automatically select a market for the application. Under the current caching documentation, server-side subrequest caching requires a cache instance and a strategy selected for each query. Queries without a strategy, mutations, and errors are not cached. Keys depend on the query and variables, while stale-while-revalidate may still return an older value; framework caches require their own review. Defining invalidation events remains project work, not evidence that the platform has already executed them automatically.
SEO and GEO
After deployment, sample product and content pages across markets and compare the initial response, post-script visible content, and structured data for consistent body content, prices, currencies, and links. Check crawler access, redirects, and canonical targets against the intended pages, then repeat the checks after cache updates and rollback. An edge node answering a request does not establish that the page is correctly crawlable or its facts remain fresh. Measure speed improvements on actual pages and devices; “global edge” is not a ranking or AI-citation guarantee.
FAQ
Does Oxygen automatically make a site faster?
No. Measure rendering, data, cache, scripts, and real devices.
Can an API secret live in the frontend?
No. Keep sensitive access server-side and per environment.
What matters when caching price and stock?
Define freshness, invalidation, and re-check before checkout.
How does deployment content support GEO?
State environment, data, cache, error, monitoring, and rollback evidence.