@shopify/hydrogen 2026.4.5 → 2026.10.0-preview.2

package/skills/hydrogen-storefront-client/references/nuxt.md

@@ -0,0 +1,121 @@
+# Nuxt
+
+Nuxt needs separate server and client Storefront clients:
+
+- Server requests use a request-scoped public client created in Nitro middleware.
+- Browser refetches use a public client whose `fetch` routes through the same-origin Hydrogen SFAPI proxy.
+
+Use the `hydrogen-request-handlers` skill when wiring middleware, response-header propagation, and 404 redirects.
+
+## Server Client
+
+Create the client in server middleware where Nuxt exposes the incoming request. `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:
+
+```ts
+import {
+  createStorefrontClient,
+  createShopifyRequestContext,
+  type ShopifyRequestContext,
+} from "@shopify/hydrogen";
+
+export default defineEventHandler((event) => {
+  const request = toWebRequest(event);
+  const requestContext = createShopifyRequestContext({
+    request,
+    i18n: { country: "US", language: "EN" },
+  });
+
+  event.context.storefrontClient = createPublicStorefrontClient(requestContext);
+  event.context.shopifyRequestContext = requestContext;
+});
+
+function createPublicStorefrontClient(requestContext: ShopifyRequestContext) {
+  return createStorefrontClient({
+    type: "public",
+    requestContext,
+    config: {
+      storeDomain: process.env.PUBLIC_STORE_DOMAIN!,
+      publicStorefrontToken: process.env.PUBLIC_STOREFRONT_API_TOKEN,
+    },
+  });
+}
+```
+
+When upgrading to a private client, use a project helper for `getBuyerIp`. Do not infer buyer IP from untrusted headers unless the deployment's proxy chain is known.
+
+## Server Injection
+
+Expose the middleware-created client through a server plugin:
+
+```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 `#app`, `h3`, and `vue` types so `$storefrontClient` is available in pages and composables.
+
+## Client Plugin
+
+Browser-side Storefront API calls should go through the same-origin SFAPI proxy installed by `handleShopifyRoutes`. Do not call the remote store domain directly from the browser.
+
+```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`.
+
+## Query Usage
+
+In server pages, prefer the injected server client:
+
+```ts
+const { $storefrontClient } = useNuxtApp();
+const { data } = await $storefrontClient.graphql(PRODUCT_QUERY, {
+  variables: { handle },
+});
+```
+
+In client navigations or `useAsyncData` refreshes that run in the browser, the injected public client uses the proxy fetch above.
+
+## Gotchas
+
+- Keep private token access in server-only files.
+- In client plugins, read only Nuxt public runtime config values that were intentionally exposed; never read `process.env` or private tokens.
+- Apply `requestContext` response headers in a Nitro `beforeResponse` plugin; otherwise Storefront cookies can be lost.
+- Route query objects can mishandle dotted filter keys. For collection/search browsing, use Hydrogen's serialized search strings instead.

package/skills/hydrogen-storefront-client/references/query-validation.md

@@ -0,0 +1,95 @@
+# Query Validation
+
+Validate every Storefront API `gql()` document headlessly before treating Hydrogen setup as complete. Editor feedback is not enough: the Hydrogen TypeScript plugin runs inside the editor's language server, but it does not run during `tsc`.
+
+Without a headless check, a query that references a missing or renamed field can typecheck and fail only at runtime. On a product page, that can look like an empty result and get accidentally converted into a misleading 404.
+
+## Configure The Schema
+
+Hydrogen's packed plugin configures both Shopify schemas:
+
+```jsonc
+// tsconfig.json
+{
+  "compilerOptions": {
+    "plugins": [
+      {
+        "name": "@shopify/hydrogen/ts-plugin"
+      }
+    ]
+  }
+}
+```
+
+If the app already has TypeScript plugins, append the Hydrogen plugin without removing framework plugins such as Next.js `name: "next"`. If the app's `tsconfig.json` extends a generated framework config, put `compilerOptions.plugins` in the extending `tsconfig.json`.
+
+The plugin writes `storefront-graphql-env.d.ts` and `customer-account-graphql-env.d.ts` at the project root. Ignore these generated files. Customer Account API documents use the separate `@shopify/hydrogen/customer-account` helper but need no additional plugin configuration.
+
+The editor must use the workspace TypeScript version for inline feedback. The CLI works independently of the editor setting.
+
+## Add A CI Check
+
+Add a script that runs the GraphQL validation:
+
+```jsonc
+// package.json
+{
+  "scripts": {
+    "check:graphql": "hydrogen gql check"
+  }
+}
+```
+
+Then chain it into the existing typecheck or check command. Run the framework's route type generation first when the app needs it, then TypeScript, then the GraphQL check:
+
+```jsonc
+// package.json
+{
+  "scripts": {
+    "typecheck": "react-router typegen && tsc && hydrogen gql check"
+  }
+}
+```
+
+For apps without route type generation, use the same ordering without that first command:
+
+```jsonc
+// package.json
+{
+  "scripts": {
+    "typecheck": "tsc && hydrogen gql check"
+  }
+}
+```
+
+For framework typecheck commands, append the GraphQL check after the framework check.
+
+Run the package script before finishing any setup that added or changed Storefront API or Customer Account API queries, including additive fragments passed to Hydrogen helpers such as predictive search query builders. Without a script, run `npx @shopify/hydrogen gql check`.
+
+For stricter CI, append `--fail-on-warn` to the package script so warning-level findings fail the build too.
+
+## What It Catches
+
+- Fields that do not exist on the selected type.
+- Invalid arguments or argument types.
+- Invalid selections, such as selecting subfields from a scalar.
+- Other schema validation errors available from the bundled Shopify GraphQL schemas.
+
+## What It Does Not Catch
+
+- Store-specific runtime constraints.
+- API-version drift where the bundled schema accepts a field but the target store rejects it.
+- Auth, market, or argument-value errors that only the live API can enforce.
+
+For live-only failures, add an integration test or smoke check that executes each critical query and asserts the response has no `errors` value.
+
+## Select `__typename` When You Narrow On It
+
+gql.tada does NOT auto-inject `__typename` for inline fragments (`... on MediaImage { ... }`). Whenever you narrow runtime nodes by `__typename` (`search.nodes`, `product.media.nodes`, any heterogeneous `nodes` union), select `__typename` explicitly — otherwise a guard like `node.__typename === "MediaImage"` silently yields empty (no type or runtime error, just missing output).
+
+```graphql
+# bad — guard never matches
+query { product { media(first: 10) { nodes { ... on MediaImage { url } } } } }
+# good
+query { product { media(first: 10) { nodes { __typename ... on MediaImage { url } } } } }
+```

package/skills/hydrogen-storefront-client/references/react-router.md

@@ -0,0 +1,81 @@
+# React Router 7
+
+Middleware creates a per-request public client. `requestContext` carries request lifecycle headers and captures SFAPI response headers so middleware can merge them into the final response. `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.
+
+```ts
+// app/storefront.context.ts
+import { createContext } from "react-router";
+import type { StorefrontClient } from "@shopify/hydrogen";
+
+export const storefrontContext = createContext<StorefrontClient>();
+```
+
+This `createContext` is React Router's request context for passing values from middleware to loaders; it is not React's component `createContext`.
+
+```ts
+// app/storefront.middleware.ts
+import {
+  createStorefrontClient,
+  createShopifyRequestContext,
+} from "@shopify/hydrogen";
+import { storefrontContext } from "./storefront.context";
+import type { Route } from "./+types/root";
+
+export const storefrontMiddleware: Route.MiddlewareFunction = async (
+  { request, context },
+  next,
+) => {
+  const requestContext = createShopifyRequestContext({
+    request,
+    i18n: { country: "US", language: "EN" },
+  });
+
+  const client = createStorefrontClient({
+    type: "public",
+    requestContext,
+    config: {
+      storeDomain: process.env.PUBLIC_STORE_DOMAIN!,
+      publicStorefrontToken: process.env.PUBLIC_STOREFRONT_API_TOKEN,
+    },
+  });
+
+  context.set(storefrontContext, client);
+
+  const response = await next();
+  requestContext.applyResponseHeaders(response.headers);
+  return response;
+};
+```
+
+```ts
+// app/root.tsx — wire up middleware
+import { storefrontMiddleware } from "./storefront.middleware";
+import type { Route } from "./+types/root";
+
+export const middleware: Route.MiddlewareFunction[] = [storefrontMiddleware];
+```
+
+Verify React Router framework middleware is enabled with `future.v8_middleware: true` in `react-router.config.ts`. If the app also needs Hydrogen route handlers and Shopify redirects, use the `hydrogen-request-handlers` React Router shape so this client creation, `handleShopifyRoutes()`, context setup, `handleShopifyRedirects()`, and response-header propagation all live in one root middleware chain.
+
+```ts
+// app/routes/product.tsx — loader reads client from context
+import { storefrontContext } from "~/storefront.context";
+import { gql } from "@shopify/hydrogen";
+import type { Route } from "./+types/product";
+
+const PRODUCT_QUERY = gql(`
+  query Product($handle: String!) {
+    product(handle: $handle) { title description }
+  }
+`);
+
+export async function loader({ context, params }: Route.LoaderArgs) {
+  const client = context.get(storefrontContext);
+  const { data } = await client.graphql(PRODUCT_QUERY, {
+    variables: { handle: params.handle },
+  });
+  return { product: data?.product };
+}
+```
+
+Because `requestContext` is created in the middleware, loaders don't need to pass `request` to `graphql()` — the client is ready to use directly from context. The request context captures SFAPI response headers, and the middleware merges them after `next()` returns so `Set-Cookie` and other headers propagate to the browser without each loader handling them.

package/skills/hydrogen-storefront-client/references/solidstart.md

@@ -0,0 +1,131 @@
+# SolidStart
+
+SolidStart uses Vinxi (Nitro under the hood) and provides middleware via `createMiddleware`. Server-side data fetching happens in `query()` functions marked with `"use server"`, where `getRequestEvent()` gives access to the request.
+
+## SSR
+
+The middleware creates the client per-request and attaches it to `event.locals`. Server functions retrieve it via `getRequestEvent()`. 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.
+
+```ts
+// src/middleware.ts
+import { createMiddleware } from "@solidjs/start/middleware";
+import {
+  createStorefrontClient,
+  createShopifyRequestContext,
+} from "@shopify/hydrogen";
+
+export default createMiddleware({
+  onRequest: (event) => {
+    const requestContext = createShopifyRequestContext({
+      request: event.request,
+      i18n: { country: "US", language: "EN" },
+    });
+
+    const client = createStorefrontClient({
+      type: "public",
+      requestContext,
+      config: {
+        storeDomain: process.env.PUBLIC_STORE_DOMAIN!,
+        publicStorefrontToken: process.env.PUBLIC_STOREFRONT_API_TOKEN,
+      },
+    });
+
+    event.locals.storefront = client;
+  },
+});
+```
+
+```ts
+// src/lib/storefront.ts — helper to retrieve the client in server functions
+import { getRequestEvent } from "solid-js/web";
+import type { StorefrontClient } from "@shopify/hydrogen";
+
+export function getStorefront(): StorefrontClient {
+  const event = getRequestEvent();
+  if (!event?.locals?.storefront) {
+    throw new Error("Storefront client not found — is the middleware registered?");
+  }
+  return event.locals.storefront as StorefrontClient;
+}
+```
+
+```tsx
+// src/routes/products/[handle].tsx
+import { query, createAsync, useParams, type RouteDefinition } from "@solidjs/router";
+import { gql } from "@shopify/hydrogen";
+import { getStorefront } from "../lib/storefront";
+import { Show } from "solid-js";
+
+const PRODUCT_QUERY = gql(`
+  query Product($handle: String!) {
+    product(handle: $handle) { title description }
+  }
+`);
+
+const fetchProduct = query(async (handle: string) => {
+  "use server";
+  const client = getStorefront();
+  const { data } = await client.graphql(PRODUCT_QUERY, {
+    variables: { handle },
+  });
+  return data?.product ?? null;
+}, "product");
+
+export const route = {
+  preload: ({ params }) => fetchProduct(params.handle),
+} satisfies RouteDefinition;
+
+export default function ProductPage() {
+  const params = useParams<{ handle: string }>();
+  const product = createAsync(() => fetchProduct(params.handle));
+
+  return (
+    <Show when={product()}>
+      {(p) => <h1>{p().title}</h1>}
+    </Show>
+  );
+}
+```
+
+## Forwarding response headers
+
+Use `onBeforeResponse` to merge captured SFAPI headers into the final response.
+
+```ts
+// src/middleware.ts — with response header propagation
+import { createMiddleware } from "@solidjs/start/middleware";
+import {
+  createStorefrontClient,
+  createShopifyRequestContext,
+} from "@shopify/hydrogen";
+
+export default createMiddleware({
+  onRequest: (event) => {
+    const requestContext = createShopifyRequestContext({
+      request: event.request,
+      i18n: { country: "US", language: "EN" },
+    });
+
+    const client = createStorefrontClient({
+      type: "public",
+      requestContext,
+      config: {
+        storeDomain: process.env.PUBLIC_STORE_DOMAIN!,
+        publicStorefrontToken: process.env.PUBLIC_STOREFRONT_API_TOKEN,
+      },
+    });
+
+    event.locals.storefront = client;
+    event.locals.shopifyRequestContext = requestContext;
+  },
+  onBeforeResponse: (event) => {
+    event.locals.shopifyRequestContext?.applyResponseHeaders(event.response.headers);
+  },
+});
+```
+
+## Footguns
+
+- **`"use server"` boundary is mandatory** — `getRequestEvent()` only works inside a `"use server"` function. Calling it outside (e.g. in a component body) returns `undefined` and the storefront client lookup silently fails.
+- **`event.nativeEvent` breaks tree-shaking** — accessing the underlying H3 event from Vinxi pulls in the entire H3 runtime. Only use it in server-only files if you need Nitro-specific features.
+- **No built-in `getClientAddress()`** — relevant when upgrading to a private client: unlike SvelteKit, SolidStart doesn't have a convenience method for the client IP. Do not trust generic proxy headers unless your deployment strips or overwrites them; build `buyerIp` from request data your deployment controls.

package/skills/hydrogen-storefront-client/references/sveltekit.md

@@ -0,0 +1,169 @@
+# SvelteKit
+
+## Contents
+
+- SSR
+- Forwarding response headers
+- Static pages (no buyer IP)
+- Footguns
+
+SvelteKit's `handle` hook in `hooks.server.ts` runs on every server request and receives an `event` object with the full `Request`, cookies, and client address. Use `event.locals` to pass the storefront client to `load` functions.
+
+## SSR
+
+The scaffold defaults to a public client; `PUBLIC_STOREFRONT_API_TOKEN` may be unset, which means tokenless access (all mock.shop supports) — read it through `$env/dynamic/public`, since `$env/static/public` fails the build for unset vars. Once the app has a private token and trusted buyer context, switch to `type: "private"` and resolve `buyerIp` (e.g. from `event.getClientAddress()`) per the `hydrogen-storefront-client` buyer-IP guidance.
+
+```ts
+// src/hooks.server.ts
+import type { Handle } from "@sveltejs/kit";
+import {
+  createStorefrontClient,
+  createShopifyRequestContext,
+} from "@shopify/hydrogen";
+import { env } from "$env/dynamic/public";
+import { PUBLIC_STORE_DOMAIN } from "$env/static/public";
+
+export const handle: Handle = async ({ event, resolve }) => {
+  const requestContext = createShopifyRequestContext({
+    request: event.request,
+    i18n: { country: "US", language: "EN" },
+  });
+  const client = createStorefrontClient({
+    type: "public",
+    requestContext,
+    config: {
+      storeDomain: PUBLIC_STORE_DOMAIN,
+      publicStorefrontToken: env.PUBLIC_STOREFRONT_API_TOKEN,
+    },
+  });
+
+  event.locals.storefront = client;
+
+  const response = await resolve(event);
+  requestContext.applyResponseHeaders(response.headers);
+  return response;
+};
+```
+
+```ts
+// src/app.d.ts — type the locals object
+import type { StorefrontClient } from "@shopify/hydrogen";
+
+declare global {
+  namespace App {
+    interface Locals {
+      storefront: StorefrontClient;
+    }
+  }
+}
+
+export {};
+```
+
+```ts
+// src/routes/products/[handle]/+page.server.ts
+import { error } from "@sveltejs/kit";
+import { gql } from "@shopify/hydrogen";
+import type { PageServerLoad } from "./$types";
+
+const PRODUCT_QUERY = gql(`
+  query Product($handle: String!) {
+    product(handle: $handle) { title description }
+  }
+`);
+
+export const load: PageServerLoad = async ({ params, locals }) => {
+  const { data } = await locals.storefront.graphql(PRODUCT_QUERY, {
+    variables: { handle: params.handle },
+  });
+  if (!data?.product) error(404, "Product not found");
+  return { product: data.product };
+};
+```
+
+## Forwarding response headers
+
+`requestContext` captures SFAPI response headers. Apply them to the framework response after routing.
+
+```ts
+// src/hooks.server.ts — response header propagation
+import { env } from "$env/dynamic/public";
+import { PUBLIC_STORE_DOMAIN } from "$env/static/public";
+
+export const handle: Handle = async ({ event, resolve }) => {
+  const requestContext = createShopifyRequestContext({
+    request: event.request,
+    i18n: { country: "US", language: "EN" },
+  });
+
+  const client = createStorefrontClient({
+    type: "public",
+    requestContext,
+    config: {
+      storeDomain: PUBLIC_STORE_DOMAIN,
+      publicStorefrontToken: env.PUBLIC_STOREFRONT_API_TOKEN,
+    },
+  });
+
+  event.locals.storefront = client;
+
+  const response = await resolve(event);
+  requestContext.applyResponseHeaders(response.headers);
+  return response;
+};
+```
+
+## Static pages (no buyer IP)
+
+For prerendered pages, use a module-scoped `private_no_buyer_context` client and export `prerender = true`.
+
+```ts
+// src/lib/storefront-static.ts
+import { createStorefrontClient, createShopifyRequestContext } from "@shopify/hydrogen";
+import { PRIVATE_STOREFRONT_API_TOKEN } from "$env/static/private";
+import { PUBLIC_STORE_DOMAIN } from "$env/static/public";
+
+const requestContext = createShopifyRequestContext({
+  request: { headers: new Headers() },
+  i18n: { country: "US", language: "EN" },
+});
+
+export const staticStorefrontClient = createStorefrontClient({
+  type: "private_no_buyer_context",
+  requestContext,
+  config: {
+    storeDomain: PUBLIC_STORE_DOMAIN,
+    privateStorefrontToken: PRIVATE_STOREFRONT_API_TOKEN,
+  },
+});
+```
+
+```ts
+// src/routes/collections/[handle]/+page.server.ts
+import { gql } from "@shopify/hydrogen";
+import { staticStorefrontClient } from "$lib/storefront-static";
+import type { PageServerLoad } from "./$types";
+
+export const prerender = true;
+
+const COLLECTION_QUERY = gql(`
+  query Collection($handle: String!) {
+    collection(handle: $handle) {
+      title
+      products(first: 20) { nodes { title handle } }
+    }
+  }
+`);
+
+export const load: PageServerLoad = async ({ params }) => {
+  const { data } = await staticStorefrontClient.graphql(COLLECTION_QUERY, {
+    variables: { handle: params.handle },
+  });
+  return { collection: data?.collection };
+};
+```
+
+## Footguns
+
+- **`event.getClientAddress()` needs proxy config** — relevant when upgrading to a private client that resolves `buyerIp` from it. Behind a reverse proxy, the raw address is the proxy's IP, not the buyer's. Set the `ADDRESS_HEADER` env var (e.g. `ADDRESS_HEADER=X-Forwarded-For`) and `XFF_DEPTH` to the number of trusted proxies so SvelteKit reads the correct IP from the right end of the header.
+- **`filterSerializedResponseHeaders` is unrelated** — this option on `resolve()` controls which headers from SvelteKit's internal `fetch()` calls are serialized into the HTML for client-side hydration. It does not affect the actual HTTP response headers. Don't confuse it with forwarding SFAPI headers.