Wire Hydrogen request handlers

A Shopify storefront answers more than page requests. Browser scripts call the Storefront API through the storefront's own origin, apps link to cart permalinks, customers follow checkout links, and old Liquid URLs need to redirect. Hydrogen's request handlers restore these routes in a headless storefront, so apps, analytics, and agents can integrate with your storefront the same way they integrate with a theme.

In this guide, you'll wire two functions around your framework's router: handleShopifyRoutes(), which answers Shopify-owned routes before your router runs, and handleShopifyRedirects(), which checks for Shopify redirects after your router returns a 404.

Anchor to How it worksHow it works

Hydrogen's request handlers are framework-neutral, but where they run depends on your framework. React Router follows this request flow:

1. Your server creates a Shopify request context with createShopifyRequestContext(). The Storefront API client and the request handlers share it for the rest of the request.
2. handleShopifyRoutes() checks the request against the routes that Hydrogen owns. If the request matches, then it returns a response and your router never sees the request.
3. If nothing matches, then your framework routes and renders the request as usual.
4. If your router returns a 404, then handleShopifyRedirects() checks for a Shopify redirect for that URL. If one exists, then it returns the redirect.
5. If there's no redirect, then your framework renders its 404 page.
6. Before your response leaves the server, call requestContext.applyResponseHeaders(response.headers). Responses from handleShopifyRoutes() and handleShopifyRedirects() already include them.

handleShopifyRedirects() can make a Storefront API request, so it runs only after a 404.

Anchor to Routes Hydrogen handlesRoutes Hydrogen handles

handleShopifyRoutes() answers the following routes:

Checkout and cart permalink redirects outside / default to payment=shop_pay; an incoming payment parameter overrides it.

handleShopifyRedirects() handles the following requests after a 404:

• /admin, which redirects to your store's Shopify admin.
• Shopify's standard storefront paths, when route templates map them to your app's paths.
• URL redirects that the merchant configures in the Shopify admin.
• Same-origin redirects from query parameters.

Anchor to RequirementsRequirements

• Deploy a template, or add Hydrogen to an existing project.
• Create a Storefront API client in your server request lifecycle.
• Create a route templates manifest. It can be empty.
• For React Router 7, set future.v8_middleware: true in react-router.config.ts. React Router 8 turns on middleware by default.

Anchor to Step 1: Create a session managerStep 1: Create a session manager

handleShopifyRoutes() takes a session manager, which stores session values such as customer account tokens. Until you add customer accounts, you can use a session manager that keeps values in memory for the length of one request:

When you add customer accounts, replace it with a cookie-backed session manager.

Anchor to Step 2: Run Shopify routes before your routerStep 2: Run Shopify routes before your router

Create a request handler that runs before your framework's router. It creates the Storefront API client and session manager, and passes the same objects to handleShopifyRoutes() that the rest of the request uses. It also checks for Shopify redirects after a 404 and applies response headers, which the next steps describe. The createRequestStorefrontClient() helper comes from Storefront API client.

Don't await handleShopifyRoutes() right away. It returns null synchronously when no route matches, and a promise of a Response when one does. Check the result first, and then return it.

Call handleRequest() from your app's request entry point, the first server code that runs for each request. Pass a next function that runs your framework's router and returns its response. In next, store the Storefront API client in request-scoped context, so your loaders reuse it instead of creating a second client. In Nuxt, run handleShopifyRoutes() in server middleware, handleShopifyRedirects() in error.vue after a 404, and applyResponseHeaders() in Nitro's beforeResponse hook. For the React Router and Next.js code, refer to Framework wiring.

If your server wraps requests in a try/catch that converts errors into a Response, then use return await shopifyResponse inside that block, so that a rejected route reaches your error handling.

In Next.js, the entry point is proxy.ts, which replaces middleware.ts in Next.js 16. The proxy can't pass the client to Server Components, so its next function forwards the request headers instead, including the original URL in the x-storefront-url header. Keep the proxy's config.matcher broad, so that it reaches /admin, /api/cart, and /api/{version}/graphql.json. Don't narrow it to a list of Hydrogen paths, because that list goes stale when Hydrogen adds routes.

Anchor to Step 3: Check for redirects after a 404Step 3: Check for redirects after a 404

handleRequest() calls handleShopifyRedirects() only after next() returns a 404. It takes the request, the Storefront API client, and your route templates. It doesn't take a session manager.

Add one more file, so that unknown paths reach this check:

Anchor to Step 4: Register handler groupsStep 4: Register handler groups

Hydrogen features that need their own server routes come as handler groups. Create each group once at module scope, and then pass it to handleShopifyRoutes() in the handlers array of handleRequest():

The following handler groups are available:

Because handleShopifyRoutes() answers these routes, your app doesn't need route files for them.

Link to the customer account routes with plain <a> and <form> elements, not your framework's client-side navigation components such as next/link or React Router's <Link> and <Form>.

Anchor to Step 5: Apply response headersStep 5: Apply response headers

Captured Shopify cookies reach non-HTML responses to non-document requests other than GET or HEAD when the request has an essential cookie, is a consent request, or explicitly establishes a session. Hydrogen computes cache-safety headers locally.

• Responses that handleShopifyRoutes() and handleShopifyRedirects() return already include these headers. Return them as they are.
• For every other response, call requestContext.applyResponseHeaders(response.headers) at the final response boundary, as the code in step 2 does.

If your app commits session cookies, then append the session headers to the response in handleRequest() first, and then call applyResponseHeaders():

Wire request handlers into your production server code, not a development-only hook. Hydrogen limits only /graphiql to development.

Anchor to Step 6: Verify your wiringStep 6: Verify your wiring

Start your development server, and then send the following requests. Replace <port> with your server's port and {version} with the Storefront API version that your client uses.

1. Query the Storefront API proxy:

   Terminal

   Copy

   1

   2

   3

   curl -i -X POST http://localhost:<port>/api/{version}/graphql.json \

   -H "content-type: application/json" \

   -d '{"query":"{ shop { name } }"}'

   The response is Storefront API JSON, not your framework's 404 page. The proxy forwards the X-Shopify-Storefront-Access-Token header from the request when one is present. It doesn't add a token from your server config.

2. Request /admin:

   Terminal

   Copy

   1

   curl -i http://localhost:<port>/admin

   The response redirects to your store's Shopify admin.

3. Request a path that doesn't exist:

   Terminal

   Copy

   1

   curl -i http://localhost:<port>/this-does-not-exist

   The response is your framework's 404 page, unless the store has a URL redirect for that path.

4. If you registered the cart handlers, then request /api/cart:

   Terminal

   Copy

   1

   curl -i http://localhost:<port>/api/cart

   Without a cart cookie, the response body is {"cart":null}.

5. Request a product URL with a Liquid-style variant ID, such as /products/{handle}?variant={numeric_id}. Use your app's product path if your route templates change it. The response is a 302 redirect to the same product with option parameters. An invalid ID, such as ?variant=garbage, renders the product page as usual.

6. If your route templates include productInCollection, then request a collection-scoped product URL:

   Terminal

   Copy

   1

   curl -i http://localhost:<port>/collections/{collection_handle}/products/{product_handle}

   The response redirects after a router 404 to the path in your template.

7. If your route templates include a custom product path, then request /products/{handle}. The response redirects after a router 404 to your product path.

For the full list of checks, refer to the production checklist.

Anchor to Framework wiringFramework wiring

Hydrogen is framework-agnostic. This section shows where its pieces go in a React Router app and a Next.js App Router app, using code trimmed from the React Router and Next.js templates. For other frameworks, refer to Other frameworks.

import type {StorefrontClient} from '@shopify/hydrogen';
import {createContext} from 'react-router';

export const storefrontContext = createContext<StorefrontClient>();

import type {Route} from './+types/root';
import {storefrontContext} from './lib/context';
import {handleRequest} from './lib/shopify';

export const middleware: Route.MiddlewareFunction[] = [
  ({request, context}, next) =>
    handleRequest(request, async (_request, storefrontClient) => {
      context.set(storefrontContext, storefrontClient);
      return next();
    }),
];

import {Suspense} from 'react';

import {ShopifyScriptsWithNavigation} from '@/components/ShopifyScriptsWithNavigation';
import {getAnalyticsShop} from '@/lib/analytics-shop';
import {shop} from '@/lib/config';

import {AppShell} from './app-shell';

export default async function RootLayout({children}: {children: React.ReactNode}) {
  const {currency} = await getAnalyticsShop();

  return (
    <html lang="en">
      <head>
        <ShopifyScriptsWithNavigation shop={shop} currency={currency} />
      </head>
      <body>
        <Suspense fallback={null}>
          <AppShell>{children}</AppShell>
        </Suspense>
      </body>
    </html>
  );
}

import {connection} from 'next/server';

import {cartHandlers} from '@/lib/cart-handlers';
import {getStorefrontClient} from '@/lib/storefront';

import {Providers} from './providers';

export async function AppShell({children}: {children: React.ReactNode}) {
  await connection();

  // Don't await the cart, so the shell can stream.
  const cartData = getStorefrontClient().then((storefrontClient) =>
    cartHandlers.get({storefrontClient}).then((result) => result.data),
  );

  return <Providers cartData={cartData}>{children}</Providers>;
}

'use client';

import type {ReactNode} from 'react';

import {CartProvider} from '@/lib/cart';
import type {cartHandlers} from '@/lib/cart-handlers';

export type CartData = Awaited<ReturnType<typeof cartHandlers.get>>['data'];

export function Providers({
  cartData,
  children,
}: {
  cartData?: Promise<CartData>;
  children: ReactNode;
}) {
  return <CartProvider initialData={cartData}>{children}</CartProvider>;
}

'use client';

import {ShopifyScripts, type ShopifyScriptsProps} from '@shopify/hydrogen/react';
import {useRouter} from 'next/navigation';

import {analyticsConsent, defaultI18n} from '@/lib/config';
import {routeTemplates} from '@/lib/route-templates';

type ShopConfig = NonNullable<ShopifyScriptsProps['shop']>;

export function ShopifyScriptsWithNavigation({
  shop,
  currency,
}: {
  shop: ShopConfig;
  currency: string;
}) {
  const router = useRouter();

  return (
    <ShopifyScripts
      i18n={{...defaultI18n, currency}}
      shop={shop}
      consent={analyticsConsent}
      navigate={(url: string) => router.push(url)}
      routes={routeTemplates}
    />
  );
}

import type {StorefrontClient} from '@shopify/hydrogen';
import {createContext} from 'react-router';

export const storefrontContext = createContext<StorefrontClient>();

import type {Route} from './+types/root';
import {storefrontContext} from './lib/context';
import {handleRequest} from './lib/shopify';

export const middleware: Route.MiddlewareFunction[] = [
  ({request, context}, next) =>
    handleRequest(request, async (_request, storefrontClient) => {
      context.set(storefrontContext, storefrontClient);
      return next();
    }),
];

Anchor to Other frameworksOther frameworks

The steps on this page work in any framework that gives your server code the incoming Request. The following table shows where each piece goes in frameworks that don't have a template. Each framework links to a development example in the Hydrogen repository that shows the full wiring. The examples show how the pieces fit together, but they aren't starter templates.

In Nuxt, server middleware receives an H3 event instead of a Request. Convert it with toWebRequest(event) before you pass it to Hydrogen, and return a matched Shopify route with sendWebResponse(event, response).

To load Shopify's scripts, call initializeShopifyScripts() from @shopify/hydrogen once in your root layout after it mounts. Pass your route templates, and your router's navigate function if it has one.

Anchor to Next stepsNext steps

Build cart UI

Register the cart handlers and build a cart that works with and without JavaScript.

Request handling reference

Review the options for Shopify routes, custom route handlers, and redirects.