Skip to main content

Deploy to other runtimes

Choose a host that supports your framework and Hydrogen's runtime requirements.

Anchor to VercelVercel

If you're not using Oxygen, then we recommend deploying to Vercel. Vercel Shop, Vercel's Next.js template, deploys to Vercel with its default Next.js settings. To deploy, follow Vercel's Next.js on Vercel guide.

Anchor to Environment variablesEnvironment variables

Add your store's environment variables in Vercel's project settings. Server-only values don't use the NEXT_PUBLIC_ prefix. Vercel Shop's build fails until you set its required variables. For their names, refer to Vercel Shop's environment variables.

Anchor to Buyer IPBuyer IP

The buyer's IP address is the first address in the x-forwarded-for header:

Buyer IP on Vercel

lib/buyer-ip.ts
export function getBuyerIp(headers: Pick<Headers, 'get'>): string {
const buyerIp = headers.get('x-forwarded-for')?.split(',')[0]?.trim();
if (buyerIp) return buyerIp;

if (process.env.NODE_ENV !== 'production') return '127.0.0.1';

throw new Error('x-forwarded-for is required for private Storefront API clients');
}

Anchor to CacheCache

To use Vercel's runtime cache, install @vercel/functions, get the cache from it in proxy.ts, and pass it to the Storefront API client with the proxy event's waitUntil:

Vercel runtime cache

proxy.ts
import {type CacheInstance} from '@shopify/hydrogen';
import {getCache} from '@vercel/functions';
import type {NextFetchEvent, NextRequest} from 'next/server';

export async function proxy(request: NextRequest, event: NextFetchEvent) {
const cache: CacheInstance | undefined = process.env.VERCEL
? getCache({namespace: 'hydrogen-v1', keyHashFunction: (key) => key})
: undefined;
const waitUntil = event.waitUntil.bind(event);

// Pass cache and waitUntil to createStorefrontClient().
// ...
}

Anchor to Node, Cloudflare Workers, and DenoNode, Cloudflare Workers, and Deno

Use your framework's adapter for the runtime, and then do the following:

  1. Create the request context, Storefront API client, Customer Account API client, and session managers inside each request.
  2. Read the buyer IP from your platform's trusted header, and pass it as buyerIp to createShopifyRequestContext().
  3. Read secrets in server code only.
  4. If your platform has a cache and waitUntil, then pass them to the Storefront API client. On Cloudflare Workers, use caches.open() and the execution context's waitUntil, as on Oxygen.
  5. Confirm that handleShopifyRoutes() runs before your router and handleShopifyRedirects() runs after a 404 in the production build.

Anchor to Next stepsNext steps

Production checklist

Check your storefront's request handlers, cart, and analytics before you launch.

Caching

Configure how the Storefront API client caches queries.

Was this page helpful?