Request context
The createShopifyRequestContext function creates the context for one incoming request. Use the context to forward the customer's cookies, locale, and IP address to Shopify, and to apply Hydrogen's response headers.
Import createShopifyRequestContext from @shopify/hydrogen.
Create one context per request, and pass the same context to createStorefrontClient, createCustomerAccountClient, and handleShopifyRoutes.
Anchor to Context setupContext setup
Creates the context for one incoming request. Pass the same context to the Storefront API client, the Customer Account API client, and . The context forwards the customer's cookies, locale, and privacy signal to Shopify, and adds Shopify's cookies and cache headers to your response.
Call on each response that your app builds. Pass with the customer's trusted IP address when you use a private Storefront API client. The function throws when i18n lacks a country or language, and when is an empty string.
- Anchor to inputinputinputShopifyRequestContextInputBase<I18n> & { buyerIp?: string; }ShopifyRequestContextInputBase<I18n> & { buyerIp?: string; }requiredrequired
The incoming request, its locale, and the customer's IP address for private Storefront API clients.
The context to pass to Hydrogen's API clients and route handlers for this request.
ShopifyRequestContextInputBase
The incoming request and its locale.
- i18n
The request's language, country, and optional localized path prefix.
I18n - request
The incoming request from your framework. When the framework exposes no request, such as during prerendering, pass `{ headers: new Headers() }`.
StorefrontRequest
StorefrontRequest
The incoming request's headers, plus its method, abort signal, and URL when the framework provides them.
Pick<Request, "headers"> & Partial<Pick<Request, "method" | "signal" | "url">>ShopifyRequestContext
The context for one request. Pass the context to Hydrogen's API clients and route handlers for that request.
ShopifyRequestContextBase & {
i18n: NormalizedI18nConfig<I18n>;
}ShopifyRequestContextBase
The fields and methods on every request context.
- __hydrogenShopifyRequestContextBrand
A type-only marker. Create request contexts only with `createShopifyRequestContext`.
never - applyResponseHeaders
Adds the headers that a Hydrogen storefront needs to the final response. Call the method on each response that your app builds. Responses from `handleShopifyRoutes` and `handleShopifyRedirects` already carry these headers. Append your committed session headers before you call the method. The method makes any response that sets a cookie private and uncacheable. The method also sets the `powered-by` header, makes responses that hold customer data private and uncacheable, and adds eligible Shopify cookies only to non-document responses for methods other than `GET` and `HEAD`.
(headers: Headers) => void - applyStorefrontRequestHeaders
Adds the Hydrogen SDK headers and the customer's cookie, privacy, and origin headers to a Storefront API request. The Storefront API client and the API proxies call the method for you.
(headers: Headers) => void - buyerIp
The customer's trusted IP address. Private Storefront API clients require it.
string - captureSubrequestHeaders
Saves the cookies from the first Storefront API response that sets cookies. The Storefront API client calls the method for you, and `applyResponseHeaders()` can add the cookies to your response.
(headers: Headers) => void - consumeStorefrontResponseHeaders
Saves the cookies from a proxied Storefront API response and removes the `set-cookie` header from that response. The API proxies in `handleShopifyRoutes` call the method for you.
(headers: Headers) => void - cookie
The incoming request's `Cookie` header. Hydrogen forwards the header to the Storefront API.
string - getForwardedRequestHeaders
Returns the incoming request's headers with Shopify's request headers added. Pass the headers when you forward the request to a proxy or another origin.
() => Headers - i18n
The request's language, country, and path prefix. The path prefix starts with `/` and has no trailing slash, or is an empty string when you don't set one.
NormalizedI18nConfig - markResponseAsPersonalized
Marks the final response as private and uncacheable because the response holds customer data. The Customer Account API client and the customer session call the method for you.
(reason: string) => void - markResponseAsSessionEstablishing
Lets the final response set Shopify cookies before the customer has a Shopify session, and marks the response as private and uncacheable. The UCP MCP proxy calls the method for you.
(reason: string) => void - requestGroupId
The ID that groups this request's Shopify API calls. Hydrogen reads the ID from the request headers or generates one.
string - signal
The incoming request's abort signal. Hydrogen's API clients stop their requests when the signal aborts.
AbortSignal - storefrontOrigin
The origin of the incoming request's URL. Hydrogen forwards the origin to the Storefront API.
string - url
The incoming request's URL.
string
Headers
NormalizedI18nConfig
The request's locale, with a path prefix that starts with `/` or is an empty string.
Omit<I18n, "pathPrefix"> & {
pathPrefix: string;
}I18nConfig
The language, country, and optional localized path prefix for a request.
- country
The request's country.
ShopifyCountryCode - language
The request's language.
ShopifyLanguageCode - pathPrefix
The URL prefix for localized routes, such as `/es-es`. Hydrogen adds the prefix to standard route redirects and product variant URLs.
string
ShopifyCountryCode
A country code that both the Storefront API and the Customer Account API accept.
ShopifyLanguageCode
A language code that both the Storefront API and the Customer Account API accept.
TypeScript
Examples
Description
Create a context for the incoming request and build a client from it. This example applies the context's response headers to the final response.
TypeScript
import { createShopifyRequestContext, createStorefrontClient, type StorefrontClient, } from "@shopify/hydrogen"; export async function handleRequest( request: Request, next: (storefront: StorefrontClient) => Promise<Response>, ) { const requestContext = createShopifyRequestContext({ request, i18n: { country: "US", language: "EN" }, }); const storefront = createStorefrontClient({ type: "public", requestContext, config: { storeDomain: process.env.PUBLIC_STORE_DOMAIN! }, }); const routedResponse = await next(storefront); const response = new Response(routedResponse.body, routedResponse); requestContext.applyResponseHeaders(response.headers); return response; }Description
Create a context without a request for prerendering. This example builds a `private_no_buyer_context` client with a localized `pathPrefix`.
TypeScript
import { createShopifyRequestContext, createStorefrontClient } from "@shopify/hydrogen"; const requestContext = createShopifyRequestContext({ request: { headers: new Headers() }, i18n: { country: "CA", language: "FR", pathPrefix: "/fr-ca" }, }); export const prerenderStorefront = createStorefrontClient({ type: "private_no_buyer_context", requestContext, config: { storeDomain: process.env.PUBLIC_STORE_DOMAIN!, privateStorefrontToken: process.env.PRIVATE_STOREFRONT_API_TOKEN!, }, });