Section B
Request handlers
handleShopifyRoutes() runs in the root middleware before React Router and owns Shopify's endpoints. handleShopifyRedirects() runs only after the router returns a 404. Probe each endpoint below: requests are made from the server so you can see real status codes, redirects and headers.
Shopify route handling
Cart API, predictive search, checkout redirect, cart permalinks, the SFAPI proxy, ?variant= redirects, /admin, robots and UCP discovery.
- Hydrogen API
handleShopifyRouteshandleShopifyRedirectscreateCartServerHandlerscreatePredictiveSearchServerHandlersdefineShopifyRouteTemplates- Data
- Hydrogen handlers + mock SFAPI
- Docs
.claude/skills/hydrogen-request-handlers/SKILL.md
export const shopifyMiddleware: MiddlewareFunction<Response> = async ({ request, context }, next) => {
const requestContext = createShopifyRequestContext({ request, i18n });
const storefront = createStorefrontClient({ type: "public", requestContext, config });
const shopifyRoute = handleShopifyRoutes({
request, requestContext, storefrontClient: storefront, sessionManager,
routeTemplates, handlers: [cartHandlers, predictiveSearchHandlers],
});
if (shopifyRoute) return shopifyRoute; // never awaited before the null check
context.set(shopifyContext, { storefront, requestContext /* … */ });
const response = await next();
if (response.status === 404) {
const redirect = await handleShopifyRedirects({ request, storefrontClient: storefront, routeTemplates });
if (redirect) return redirect;
}
requestContext.applyResponseHeaders(response.headers);
return response;
};Checkout handling
/checkout loads the cart from the cart cookie and redirects to cart.checkoutUrl. In demo mode that URL is the local checkout demonstration.
- Hydrogen API
handleShopifyRoutes (/checkout)- Data
- Mock cart checkoutUrl / real Shopify Checkout
- Docs
.claude/skills/hydrogen-request-handlers/SKILL.md
See it in the store:Demo checkout page
URL redirects & /admin
After a 404, Hydrogen checks Shopify URL redirects, standard-route redirects and /admin. Storefront URL redirects need a real store.
- Hydrogen API
handleShopifyRedirects- Data
- Your store's URL redirects
- Docs
.claude/skills/hydrogen-request-handlers/SKILL.md