About deploying Hydrogen storefronts
Hydrogen's core uses web platform APIs. Your framework determines where you can deploy a Hydrogen storefront. The React Router starter template deploys to Oxygen, Shopify's hosting platform for storefronts. Vercel Shop, Vercel's Next.js template, deploys to Vercel.
Anchor to How it worksHow it works
Wherever you deploy, a Hydrogen storefront needs the same things from its runtime:
- Request-scoped state: Create the request context, Storefront API client, Customer Account API client, and session managers inside each request. Only pure constants and stateless factories, such as handler groups and route templates, belong at module scope.
- Server-only secrets: Read the private Storefront API token and session secret in server code only. On runtimes that pass environment bindings to the request handler, such as Oxygen, read them from those bindings instead of
process.env. - A trusted buyer IP: Storefront API clients with
type: 'private'need the buyer's IP address. Hydrogen doesn't infer it, because each platform sets it in a different header. - A cache and
waitUntil: Pass the platform's cache and itswaitUntilfunction to the Storefront API client so that cached queries can revalidate in the background after the storefront sends the response. For more information, refer to Caching. - Request handlers in production code: Wire
handleShopifyRoutes()andhandleShopifyRedirects()into your production server, not a development-only hook. Refer to Request handlers.
The following table lists the buyer IP header for common platforms:
| Platform | Buyer IP header |
|---|---|
| Oxygen | oxygen-buyer-ip |
| Vercel | x-forwarded-for (use the first address) |
| Cloudflare | CF-Connecting-IP |
| Fly.io | Fly-Client-IP |
On Fly.io, parse X-Forwarded-For only when another reverse proxy sits in front of your app.
Anchor to Choose where to deployChoose where to deploy
| Runtime | When to use it | Guide |
|---|---|---|
| Oxygen | You want Shopify to host your storefront, with environments, preview deployments, and environment variables managed in the Shopify admin. | Deploy to Oxygen |
| Vercel | You're building with Next.js, or you're not using Oxygen. | Vercel |
| Node, Cloudflare Workers, Deno, or another runtime | Your framework already deploys there. | Other runtimes |
Before you deploy to any runtime, run the production checklist against a production build.
Anchor to Next stepsNext steps
Was this page helpful?