@shopify/hydrogen 2026.4.5 → 2026.10.0-preview.2

package/skills/hydrogen-request-handlers/references/frameworks.md

@@ -0,0 +1,179 @@
+# Framework Shapes
+
+## Contents
+
+- Single-Hook Shape
+- React Router 7
+- SolidStart
+- Unknown Framework Decision Tree
+- Gotchas
+
+This reference covers React Router, SvelteKit, Astro, SolidStart, and unknown server frameworks. For Next.js, read its dedicated reference.
+
+## Single-Hook Shape
+
+Use this when one server hook can both return a `Response` before routing and inspect the resolved response status after routing. SvelteKit and Astro fit this shape.
+
+The example lets the framework handle rejected route promises, so it returns a matched promise directly. If the app instead wraps the request lifecycle in a `try/catch` that creates an error `Response`, await only after the truthy check so that boundary also catches a matched route rejection:
+
+```ts
+try {
+  const shopifyRoute = handleShopifyRoutes(options);
+  if (shopifyRoute) return await shopifyRoute;
+
+  // Continue framework routing.
+} catch (error) {
+  logger.error(error);
+  return new Response("Unexpected error", { status: 500 });
+}
+```
+
+Prefer this over adding `.catch()` only to the returned promise: the request-level boundary also handles synchronous setup and validation errors.
+
+The scaffold defaults to a public client; `PUBLIC_STOREFRONT_API_TOKEN` may be unset, which means tokenless access (all mock.shop supports). Once the app has a private token and trusted buyer context, switch to `type: "private"` and resolve `buyerIp` per the `hydrogen-storefront-client` buyer-IP guidance.
+
+This shape assumes app-owned `getBuyerIp`, `createSessionManager`, and `routeTemplates` values.
+
+```ts
+import {
+  createCartServerHandlers,
+  createPredictiveSearchServerHandlers,
+  createStorefrontClient,
+  createShopifyRequestContext,
+  handleShopifyRedirects,
+  handleShopifyRoutes,
+} from "@shopify/hydrogen";
+
+const cartHandlers = createCartServerHandlers();
+const predictiveSearchHandlers = createPredictiveSearchServerHandlers();
+
+export async function handleRequest(request: Request, next: () => Promise<Response>) {
+  const requestContext = createShopifyRequestContext({
+    request,
+    i18n: { country: "US", language: "EN" },
+  });
+  const sessionManager = await createSessionManager(request);
+  const storefrontClient = createStorefrontClient({
+    type: "public",
+    requestContext,
+    config: {
+      storeDomain: process.env.PUBLIC_STORE_DOMAIN!,
+      publicStorefrontToken: process.env.PUBLIC_STOREFRONT_API_TOKEN,
+    },
+  });
+
+  const shopifyRoute = handleShopifyRoutes({
+    request,
+    requestContext,
+    sessionManager,
+    storefrontClient,
+    routeTemplates,
+    handlers: [cartHandlers, predictiveSearchHandlers],
+  });
+  if (shopifyRoute) return shopifyRoute;
+
+  const response = await next();
+  if (response.status === 404) {
+    const redirect = await handleShopifyRedirects({ request, routeTemplates, storefrontClient });
+    if (redirect) return redirect;
+  }
+
+  storefrontClient.requestContext.applyResponseHeaders(response.headers);
+  return response;
+}
+```
+
+## React Router 7
+
+React Router framework mode needs:
+
+- Verify `future.v8_middleware: true` is set in `react-router.config.ts`.
+- A final splat route such as `route("*", "routes/catchall.tsx")`.
+- Root-route middleware that creates the Storefront client, runs Hydrogen routes, stores the client in context, and applies response headers after `next()`.
+- A public Storefront client by default; when upgrading to `type: "private"`, resolve trusted `buyerIp` before `createStorefrontClient` per the buyer-IP guidance from `hydrogen-storefront-client`.
+
+```tsx
+import {
+  createCartServerHandlers,
+  createPredictiveSearchServerHandlers,
+  createStorefrontClient,
+  createShopifyRequestContext,
+  handleShopifyRedirects,
+  handleShopifyRoutes,
+} from "@shopify/hydrogen";
+
+const cartHandlers = createCartServerHandlers();
+const predictiveSearchHandlers = createPredictiveSearchServerHandlers();
+
+export const middleware: Route.MiddlewareFunction[] = [
+  async ({ context, request }, next) => {
+    const requestContext = createShopifyRequestContext({
+      request,
+      i18n: { country: "US", language: "EN" },
+    });
+    const sessionManager = await createSessionManager(request);
+    const storefrontClient = createStorefrontClient({
+      type: "public",
+      requestContext,
+      config: {
+        storeDomain: process.env.PUBLIC_STORE_DOMAIN!,
+        publicStorefrontToken: process.env.PUBLIC_STOREFRONT_API_TOKEN,
+      },
+    });
+
+    const shopifyRoute = handleShopifyRoutes({
+      request,
+      requestContext,
+      sessionManager,
+      storefrontClient,
+      routeTemplates,
+      handlers: [cartHandlers, predictiveSearchHandlers],
+    });
+    if (shopifyRoute) return shopifyRoute;
+
+    context.set(storefrontClientContext, storefrontClient);
+
+    const response = await next();
+    if (response.status === 404) {
+      const redirect = await handleShopifyRedirects({ request, routeTemplates, storefrontClient });
+      if (redirect) return redirect;
+    }
+    storefrontClient.requestContext.applyResponseHeaders(response.headers);
+    return response;
+  },
+];
+```
+
+## SolidStart
+
+SolidStart middleware can short-circuit before routing, but cannot reliably observe the final 404 after SSR streaming starts. Put `handleShopifyRoutes` in middleware and `handleShopifyRedirects` in a last-priority catch-all route.
+
+In middleware, create an app-owned request-scoped `sessionManager` before calling `handleShopifyRoutes`:
+
+```ts
+const shopifyRoute = handleShopifyRoutes({
+  request: event.request,
+  requestContext,
+  sessionManager,
+  storefrontClient,
+  routeTemplates,
+  handlers: [cartHandlers, predictiveSearchHandlers],
+});
+if (shopifyRoute) return shopifyRoute;
+```
+
+In `src/routes/[...404].tsx`, run `handleShopifyRedirects` from a server query/preload and redirect if it returns a location. Preserve the returned status only if the framework redirect API supports it.
+
+## Unknown Framework Decision Tree
+
+1. Find the pre-routing hook. If it cannot return a `Response`, the framework cannot host `handleShopifyRoutes` correctly.
+2. If the same hook can inspect final response status, use the single-hook shape.
+3. If not, check whether the not-found UI route runs per-request server code. Use a header-pass shape like Next.
+4. If not, register a final catch-all route and run `handleShopifyRedirects` there.
+
+## Gotchas
+
+- Never run `handleShopifyRedirects` pre-routing.
+- Never run `handleShopifyRoutes` after framework routing.
+- Do not create a second Storefront client inside loaders when one already exists in request context.
+- Framework redirect helpers may turn Hydrogen's `301` into `302` or `307`.

package/skills/hydrogen-request-handlers/references/nextjs.md

@@ -0,0 +1,137 @@
+# Next.js App Router
+
+Next splits Hydrogen routing across `proxy.ts` and `app/not-found.tsx`.
+
+## `proxy.ts`
+
+`proxy.ts` can short-circuit before routing, so put `handleShopifyRoutes` there. In Next 16+, the file is `proxy.ts` and the exported function is named `proxy`; older Next projects may use `middleware.ts` with an exported `middleware` function. It cannot inspect the routed response, so forward the original URL to not-found UI.
+
+The scaffold defaults to a public client; `NEXT_PUBLIC_STOREFRONT_API_TOKEN` may be unset, which means tokenless access (all mock.shop supports). Once the app has a private token and trusted buyer context, switch to `type: "private"` and resolve `buyerIp` from the app's trusted deployment headers per the buyer-IP guidance from `hydrogen-storefront-client`.
+
+This shape assumes app-owned server-only helpers and values for `customerSession`, `createSessionManager`, and `routeTemplates`. Do not import those names from Hydrogen.
+
+```ts
+import {
+  createCartServerHandlers,
+  createShopifyRequestContext,
+  createStorefrontClient,
+  handleShopifyRoutes,
+} from "@shopify/hydrogen";
+import { createCustomerAccountServerHandlers } from "@shopify/hydrogen/customer-account";
+import { NextResponse, type NextRequest } from "next/server";
+
+const cartHandlers = createCartServerHandlers({ customerSession });
+const customerAccountHandlers = createCustomerAccountServerHandlers({
+  customerSession,
+  cartServerHandlers: cartHandlers,
+});
+
+export async function proxy(request: NextRequest) {
+  const requestContext = createShopifyRequestContext({
+    request,
+    i18n: { country: "US", language: "EN" },
+  });
+  const storefrontClient = createStorefrontClient({
+    type: "public",
+    requestContext,
+    config: {
+      storeDomain: process.env.NEXT_PUBLIC_STORE_DOMAIN!,
+      publicStorefrontToken: process.env.NEXT_PUBLIC_STOREFRONT_API_TOKEN,
+    },
+  });
+  const sessionManager = await createSessionManager(request);
+
+  const shopifyRoute = handleShopifyRoutes({
+    request,
+    requestContext,
+    sessionManager,
+    storefrontClient,
+    routeTemplates,
+    handlers: [cartHandlers, customerAccountHandlers],
+  });
+  if (shopifyRoute) return shopifyRoute;
+
+  const requestHeaders = requestContext.getForwardedRequestHeaders();
+  const response = NextResponse.next({ request: { headers: requestHeaders } });
+  requestContext.applyResponseHeaders(response.headers);
+  return response;
+}
+
+export const config = {
+  matcher: ["/((?!_next/static|_next/image|_next/data|favicon.ico).*)"],
+};
+```
+
+The proxy returns a matched promise directly so Next owns any rejection. If the app adds a request-level `try/catch` that returns a custom error response, use `return await shopifyRoute` inside that boundary after the truthy check.
+
+Use `proxy.ts` for Next 16+. Older Next projects may still use `middleware.ts`, but keep the file name and exported function name matched to the installed Next version.
+
+Keep `handleShopifyRoutes` broad inside `proxy.ts`. Do not manually whitelist Hydrogen-owned path regexes before calling it; `handleShopifyRoutes` already no-ops for unmatched app routes, and manually duplicating its route list goes stale when Hydrogen adds handlers. The matcher should exclude static Next assets, not app pages.
+
+Next docs warn that Proxy is not for slow data fetching or full session management. For Customer Account API this means `proxy.ts` may create the request context and local session manager needed by registered handlers, but access-token refresh belongs to the registered `/account/refresh` handler, not generic app-page proxy work.
+
+## `app/not-found.tsx`
+
+```tsx
+import { handleShopifyRedirects } from "@shopify/hydrogen";
+import { headers } from "next/headers";
+import { redirect } from "next/navigation";
+import { connection } from "next/server";
+import { Suspense } from "react";
+
+import { getStorefrontClient } from "@/lib/storefront";
+import { routeTemplates } from "@/lib/route-templates";
+
+export default function NotFound() {
+  return (
+    <div>
+      <Suspense fallback={null}>
+        <RedirectChecker />
+      </Suspense>
+      <h1>404</h1>
+    </div>
+  );
+}
+
+async function RedirectChecker() {
+  await connection();
+  const url = (await headers()).get("x-storefront-url");
+
+  if (url) {
+    const result = await handleShopifyRedirects({
+      request: new Request(url),
+      routeTemplates,
+      storefrontClient: await getStorefrontClient(),
+    });
+    const location = result?.headers.get("location");
+    if (location) redirect(location);
+  }
+
+  return null;
+}
+```
+
+With `cacheComponents: true`, keep request-time work in an async child under `<Suspense>` and call `connection()` before `headers()`. Do not add `export const dynamic` / `fetchCache` / `revalidate` route config under Cache Components.
+
+## Storefront Client
+
+In server components, use a cached server-only factory that reads `headers()` and creates a request-scoped client (public by default). In `proxy.ts`, use the actual `NextRequest` so URL, signal, and forwarded headers are preserved. `requestContext.getForwardedRequestHeaders()` carries the original URL through `x-storefront-url` for `not-found.tsx`.
+
+When a Server Component or layout reads Customer Account session state under Cache Components, put that read below an explicit dynamic boundary (`connection()` + `<Suspense>`). Do not rely on static route-segment config that Cache Components rejects.
+
+## Customer Account API
+
+Register the Customer Account handlers shown above with `handleShopifyRoutes`; do not create separate Next Route Handlers for the default login, authorize, refresh, or logout flow. The registered handlers own `GET /account/login`, `GET /account/authorize`, `GET /account/refresh`, and `POST /account/logout` — see `createCustomerAccountServerHandlers` for the response contract. Link to `/account/login` and submit `/account/logout` with plain `<a>`/`<form>`, not `next/link` — those handlers return raw external redirects.
+
+Because `proxy.ts` returns before RSC render begins, a session mutation made during render cannot be committed — which is why account pages read with `getAccessToken()` and delegate refresh to the registered `/account/refresh` handler.
+
+Use Server Components for read-only account state only. Header account links should call `customerSession.isLoggedIn()` through an app helper that only exposes `ReadonlyCustomerSessionManager`. Account pages that need Customer Account GraphQL should call `customerSession.getAccessToken()` first. If `isLoggedIn()` is true but `getAccessToken()` returns `undefined`, redirect once to `/account/refresh?return_to=...` and let the registered refresh handler commit new cookies before rendering private data. If `isLoggedIn()` is false, show login UI or redirect to `/account/login` instead. Include a one-shot refresh guard so a failed refresh falls back to login or an account error state instead of looping.
+
+Only expose `WritableCustomerSessionManager` inside response boundaries that can commit the session cookie, such as the registered `/account/refresh` handler or a custom route/server function that returns the final response.
+
+## Gotchas
+
+- Next's `redirect()` does not preserve Hydrogen's `301` status. If permanent redirect status matters, use a framework escape hatch that can return the `Response` directly.
+- Do not run Storefront URL redirects in `proxy.ts`; that would add a Storefront API request to every app route.
+- Keep the matcher broad enough to include `/admin`, `/api/cart`, and `/api/{api-version}/graphql.json`, but exclude static Next assets.
+- Customer Account session manager initialization should be local session storage work only, such as encrypted cookie decrypt/encrypt. Token endpoint refresh belongs to `/account/refresh`, not the generic proxy path.

package/skills/hydrogen-request-handlers/references/nuxt.md

@@ -0,0 +1,215 @@
+# Nuxt And Nitro
+
+## Contents
+
+- Server Middleware
+- Server Plugin Injection
+- Response Headers
+- 404 Redirects
+- Client Storefront Plugin
+- Gotchas
+
+Nuxt needs three pieces:
+
+1. Nitro middleware for `handleShopifyRoutes` and request-scoped client creation.
+2. A server plugin that applies captured Storefront response headers before Nitro responds.
+3. `error.vue` handling for post-routing Shopify redirects on 404.
+
+## Server Middleware
+
+Create `server/middleware/shopify.ts`:
+
+The scaffold defaults to a public client; `PUBLIC_STOREFRONT_API_TOKEN` may be unset, which means tokenless access (all mock.shop supports). Once the app has a private token and trusted buyer context, switch to `type: "private"` and resolve `buyerIp` from the app's trusted deployment headers per the buyer-IP guidance from `hydrogen-storefront-client`.
+
+Create app-owned `sessionManager` and `routeTemplates` values before `handleShopifyRoutes`; the session manager must be request-scoped.
+
+```ts
+import {
+  createCartServerHandlers,
+  createStorefrontClient,
+  createShopifyRequestContext,
+  handleShopifyRoutes,
+  type ShopifyRequestContext,
+} from "@shopify/hydrogen";
+
+const cartHandlers = createCartServerHandlers();
+
+export default defineEventHandler(async (event) => {
+  const request = toWebRequest(event);
+  const requestContext = createShopifyRequestContext({
+    request,
+    i18n: { country: "US", language: "EN" },
+  });
+  const sessionManager = await createSessionManager(request);
+  const storefrontClient = createPublicStorefrontClient(requestContext);
+
+  const shopifyRoute = handleShopifyRoutes({
+    request,
+    requestContext,
+    sessionManager,
+    storefrontClient,
+    routeTemplates,
+    handlers: [cartHandlers],
+  });
+  if (shopifyRoute) return sendWebResponse(event, await shopifyRoute);
+
+  event.context.shopifyRequestContext = requestContext;
+  event.context.storefrontClient = storefrontClient;
+});
+
+function createPublicStorefrontClient(requestContext: ShopifyRequestContext) {
+  return createStorefrontClient({
+    type: "public",
+    requestContext,
+    config: {
+      storeDomain: process.env.PUBLIC_STORE_DOMAIN!,
+      publicStorefrontToken: process.env.PUBLIC_STOREFRONT_API_TOKEN,
+    },
+  });
+}
+```
+
+This middleware awaits a matched promise because `sendWebResponse` needs the resolved `Response`; rejected promises continue through Nitro's request error handling. Do not attach an inline `.catch()` unless this route intentionally needs handling that differs from the app's normal error boundary.
+
+Use project-owned helpers for env access. Do not expose the private token to client plugins.
+
+## Server Plugin Injection
+
+Create `plugins/storefront.server.ts`:
+
+```ts
+export default defineNuxtPlugin(() => {
+  const event = useRequestEvent();
+  if (!event?.context.storefrontClient) {
+    throw new Error("Storefront client was not created for this server request.");
+  }
+
+  return {
+    provide: {
+      storefrontClient: event.context.storefrontClient,
+      shopifyRequestContext: event.context.shopifyRequestContext,
+    },
+  };
+});
+```
+
+Augment Nuxt and H3 types so `$storefrontClient` and `event.context.storefrontClient` are typed.
+
+## Response Headers
+
+Create `server/plugins/shopify-headers.ts`:
+
+```ts
+export default defineNitroPlugin((nitroApp) => {
+  nitroApp.hooks.hook("beforeResponse", (event) => {
+    const requestContext = event.context.shopifyRequestContext;
+    if (!requestContext) return;
+
+    const headers = new Headers();
+    copyHeader(event.node.res.getHeader("content-type"), (value) => {
+      headers.set("content-type", value);
+    });
+    copyHeader(event.node.res.getHeader("server-timing"), (value) => {
+      headers.append("server-timing", value);
+    });
+
+    requestContext.applyResponseHeaders(headers);
+
+    const serverTiming = headers.get("server-timing");
+    if (serverTiming) event.node.res.setHeader("server-timing", serverTiming);
+
+    const setCookies = headers.getSetCookie();
+    if (setCookies.length > 0) {
+      event.node.res.setHeader("set-cookie", [
+        ...normalizeSetCookie(event.node.res.getHeader("set-cookie")),
+        ...setCookies,
+      ]);
+    }
+  });
+});
+
+function copyHeader(value: number | string | string[] | undefined, copy: (value: string) => void) {
+  if (Array.isArray(value)) {
+    for (const item of value) copy(item);
+  } else if (value != null) {
+    copy(String(value));
+  }
+}
+
+function normalizeSetCookie(value: number | string | string[] | undefined): string[] {
+  if (Array.isArray(value)) return value;
+  if (typeof value === "string") return [value];
+  return [];
+}
+```
+
+Preserve existing `set-cookie` values when appending Storefront cookies.
+
+## 404 Redirects
+
+In `error.vue`, call `handleShopifyRedirects` only for server-side 404s:
+
+```vue
+<script setup lang="ts">
+import { handleShopifyRedirects } from "@shopify/hydrogen";
+import type { NuxtError } from "#app";
+
+const props = defineProps<{ error: NuxtError }>();
+
+if (import.meta.server && props.error.statusCode === 404) {
+  const event = useRequestEvent();
+  if (event) {
+    const request = toWebRequest(event);
+    const storefrontClient = event.context.storefrontClient;
+    if (!storefrontClient) throw new Error("Storefront client was not created.");
+    const redirect = await handleShopifyRedirects({ request, routeTemplates, storefrontClient });
+    if (redirect) {
+      const location = redirect.headers.get("location");
+      if (location) await navigateTo(location, { redirectCode: redirect.status as 301 | 302 });
+    }
+  }
+}
+</script>
+```
+
+## Client Storefront Plugin
+
+For client-side refetches, use a public client whose `fetch` rewrites Storefront API URLs to the same-origin Hydrogen SFAPI proxy:
+
+```ts
+import { createStorefrontClient, createShopifyRequestContext } from "@shopify/hydrogen";
+
+export default defineNuxtPlugin(() => {
+  const config = useRuntimeConfig().public;
+  const requestContext = createShopifyRequestContext({
+    request: { headers: new Headers() },
+    i18n: { country: "US", language: "EN" },
+  });
+  const storefrontClient = createStorefrontClient({
+    type: "public",
+    requestContext,
+    config: {
+      storeDomain: config.storeDomain,
+      publicStorefrontToken: config.storefrontApiToken,
+      fetch: (input, init) => {
+        const requestUrl = new URL(
+          typeof input === "string" ? input : input instanceof Request ? input.url : String(input),
+        );
+        const proxyUrl = new URL(requestUrl.pathname + requestUrl.search, window.location.origin);
+        return fetch(proxyUrl, init);
+      },
+    },
+  });
+
+  return { provide: { storefrontClient } };
+});
+```
+
+`storeDomain` and `storefrontApiToken` are example public runtime-config keys. Use the names already established by the app, and never expose the private Storefront token through `runtimeConfig.public`.
+
+## Gotchas
+
+- Do not call `handleShopifyRedirects` from middleware; Nuxt has not routed yet.
+- Do not let browser fetches call the remote Storefront domain directly when the same-origin proxy is installed.
+- Client plugins may read Nuxt public runtime config, but must not read `process.env` or private tokens.
+- If `Set-Cookie` from Storefront API is missing, check the Nitro `beforeResponse` plugin first.