@shopify/hydrogen 2026.4.5 → 2026.10.0-preview.2

package/skills/hydrogen-oxygen/references/react-router.md

@@ -0,0 +1,230 @@
+# React Router On Oxygen
+
+Read the core Oxygen requirements in [SKILL.md](../SKILL.md) first. This reference only maps those requirements to a
+React Router framework-mode app. Adapt names and paths to the project instead of copying files blindly.
+
+## Contents
+
+- Package scripts and dependencies
+- Vite configuration
+- React Router configuration
+- Worker entrypoint
+- Request context
+- Server and client entries
+- TypeScript adjustments
+- React Router verification
+
+## Package Scripts And Dependencies
+
+Keep the app's existing React and React Router dependencies. Keep `isbot` for bot-aware streaming. Remove
+`@react-router/node`, `@react-router/serve`, and `react-router-serve` only after replacing their runtime responsibilities
+with the entries below. Keep `@types/node` as a development dependency when Vite configuration needs it.
+
+Use React Router framework-mode commands while preserving any existing GraphQL validation:
+
+```json
+{
+  "scripts": {
+    "dev": "vite dev",
+    "build": "react-router build",
+    "preview": "react-router build && vite preview",
+    "typecheck": "react-router typegen && tsc --noEmit",
+    "deploy": "shopify hydrogen deploy"
+  }
+}
+```
+
+For example, retain `gql.tada check --fail-on-warn` in `typecheck` when the app uses the gql.tada plugin.
+
+## Vite Configuration
+
+Place the Oxygen plugin before React Router. Its order relative to unrelated plugins such as Tailwind or custom
+development plugins does not matter. Merge the following settings into the existing config and keep unrelated plugins
+the app needs:
+
+```ts
+import { reactRouter } from "@react-router/dev/vite";
+import { oxygen } from "@shopify/mini-oxygen/vite";
+import { defineConfig } from "vite";
+
+export default defineConfig({
+  plugins: [oxygen(), reactRouter()],
+  build: {
+    assetsInlineLimit: 0,
+  },
+  ssr: {
+    optimizeDeps: {
+      include: [
+        "react",
+        "react/jsx-runtime",
+        "react/jsx-dev-runtime",
+        "react-dom",
+        "react-dom/server",
+        "react-router > set-cookie-parser",
+        "react-router > cookie",
+        "react-router",
+      ],
+    },
+  },
+});
+```
+
+Keep `assetsInlineLimit: 0` for a strict Content Security Policy. Keep the `optimizeDeps` list until MiniOxygen runtime
+tests prove entries unnecessary; it prevents React Router development failures such as `module is not defined` and
+`require is not defined`.
+
+Do not add classic Hydrogen's Vite plugin or unrelated development plugins solely for Oxygen.
+
+## React Router Configuration
+
+Keep SSR enabled. Preserve existing future flags and app behavior. Middleware-based apps generally need:
+
+```ts
+import type { Config } from "@react-router/dev/config";
+
+export default {
+  ssr: true,
+  subResourceIntegrity: false,
+  future: {
+    v8_middleware: true,
+    unstable_optimizeDeps: true,
+  },
+} satisfies Config;
+```
+
+Do not force a new build directory unless the project's deployment tooling requires it.
+
+Set `subResourceIntegrity: false` because Oxygen serves the assets itself and does not need React Router's SRI manifest
+in the Worker output. Enable `unstable_optimizeDeps` so React Router honors Vite's `ssr.optimizeDeps.include` list under
+MiniOxygen.
+
+## Worker Entrypoint
+
+Add the root Worker entrypoint expected by MiniOxygen. Create the React Router request handler and context per request:
+
+```ts
+import { createRequestHandler, RouterContextProvider } from "react-router";
+import * as serverBuild from "virtual:react-router/server-build";
+
+import { createAppLoadContext } from "./app/lib/server-context";
+
+export default {
+  async fetch(request: Request, env: Env, executionContext: ExecutionContext) {
+    const handleRequest = createRequestHandler(serverBuild, import.meta.env.MODE);
+    const context = await createAppLoadContext(
+      request,
+      env,
+      executionContext,
+      new RouterContextProvider(),
+    );
+
+    return handleRequest(request, context);
+  },
+};
+```
+
+Use `import.meta.env.MODE`, not `process.env.NODE_ENV`, at this Vite boundary.
+
+## Request Context
+
+Map the platform values described in the main skill into React Router contexts:
+
+```ts
+import type { CacheInstance } from "@shopify/hydrogen";
+import { createContext } from "react-router";
+import type { RouterContextProvider } from "react-router";
+
+export const envContext = createContext<Env>();
+export const waitUntilContext = createContext<ExecutionContext["waitUntil"]>();
+export const cacheContext = createContext<CacheInstance>();
+
+export async function createAppLoadContext(
+  _request: Request,
+  env: Env,
+  executionContext: ExecutionContext,
+  provider: RouterContextProvider,
+): Promise<RouterContextProvider> {
+  const waitUntil = executionContext.waitUntil.bind(executionContext);
+  const cache = await caches.open("hydrogen");
+
+  provider.set(envContext, env);
+  provider.set(waitUntilContext, waitUntil);
+  provider.set(cacheContext, cache);
+  return provider;
+}
+```
+
+Adapt this to an existing `getLoadContext` or middleware architecture. Root middleware and loaders should read these
+values before creating the request-scoped resources required by the main skill.
+
+## Server And Client Entries
+
+Provide explicit entries after removing the Node adapter. Render with Web streams:
+
+```tsx
+import { isbot } from "isbot";
+import { renderToReadableStream } from "react-dom/server";
+import { ServerRouter } from "react-router";
+import type { EntryContext } from "react-router";
+
+export default async function handleRequest(
+  request: Request,
+  responseStatusCode: number,
+  responseHeaders: Headers,
+  reactRouterContext: EntryContext,
+) {
+  let statusCode = responseStatusCode;
+  const body = await renderToReadableStream(
+    <ServerRouter context={reactRouterContext} url={request.url} />,
+    {
+      signal: request.signal,
+      onError(error) {
+        console.error(error);
+        statusCode = 500;
+      },
+    },
+  );
+
+  if (isbot(request.headers.get("user-agent"))) await body.allReady;
+  responseHeaders.set("Content-Type", "text/html");
+  return new Response(body, { headers: responseHeaders, status: statusCode });
+}
+```
+
+Add the browser hydration entry:
+
+```tsx
+import { startTransition, StrictMode } from "react";
+import { hydrateRoot } from "react-dom/client";
+import { HydratedRouter } from "react-router/dom";
+
+startTransition(() => {
+  hydrateRoot(
+    document,
+    <StrictMode>
+      <HydratedRouter />
+    </StrictMode>,
+  );
+});
+```
+
+Do not copy entries that import classic Hydrogen CSP or nonce utilities.
+
+## TypeScript Adjustments
+
+Apply the Worker environment and type requirements from the main skill. Additionally include `react-router` and
+`vite/client` in the app TypeScript types, preserve the existing gql.tada plugin configuration, and use `import type`
+for type-only bindings under `verbatimModuleSyntax`.
+
+## React Router Verification
+
+Run React Router type generation, the app typecheck, GraphQL validation when configured, and `react-router build`.
+Search for Node adapter remnants in application and configuration files:
+
+```sh
+rg -n 'process\.env|renderToPipeableStream|@react-router/node|@react-router/serve|react-router-serve|hydrogen-classic' \
+  . -g '!node_modules' -g '!build' -g '!dist' -g '!package-lock.json' -g '!pnpm-lock.yaml'
+```
+
+Classify matches in build configuration, documentation, and transitive dependencies rather than deleting them
+mechanically. Then perform the framework-neutral MiniOxygen runtime checks from the main skill.

package/skills/hydrogen-predictive-search/SKILL.md

@@ -0,0 +1,130 @@
+---
+name: hydrogen-predictive-search
+description: >
+  Guide for building predictive search with @shopify/hydrogen. Use when adding,
+  modifying, or reviewing autocomplete/search-as-you-type UI, predictive search
+  route handlers, tracking URLs, custom predictive search fragments, or framework
+  predictive search bindings.
+---
+
+# Hydrogen Predictive Search
+
+Hydrogen predictive search has four layers:
+
+1. Storefront API query helper in `@shopify/hydrogen`.
+2. Same-origin route handler at `/api/predictive-search`.
+3. Framework-neutral client store.
+4. Framework provider/hooks or composables.
+
+Keep rendering app-owned. Hydrogen provides data, state, request lifecycle, and URL helpers — not a dropdown template.
+
+## Server Route
+
+Register the packaged route handler in the app's central `handleShopifyRoutes()` wiring before framework routing. Use the `hydrogen-request-handlers` skill for the full framework-specific request context, session manager, and Storefront client setup.
+
+```ts
+import { createPredictiveSearchServerHandlers } from "@shopify/hydrogen";
+
+const predictiveSearchHandlers = createPredictiveSearchServerHandlers();
+```
+
+Use the same request-scoped Storefront client as the app's other Hydrogen handlers and loaders. Do not create a second client inside predictive search code.
+
+The default browser predictive search endpoint is `GET /api/predictive-search`. Override it with `predictiveSearchEndpoint` when the JSON route lives elsewhere. The route accepts `q` plus optional Storefront API controls such as `limit`, `limitScope`, `types`, `searchableFields`, and `unavailableProducts`.
+
+## Framework UI
+
+When building with a UI framework, check this skill's `references/` directory for framework-specific instructions. Framework bindings share the same route, store, and URL contracts.
+
+## Tracking URLs
+
+Use `getPredictiveSearchItemUrl()` for predictive result links. It infers Hydrogen's standard storefront route from the item's `__typename` and keeps Storefront API `trackingParameters` without double-encoding:
+
+```tsx
+import { getPredictiveSearchItemUrl } from "@shopify/hydrogen";
+
+const productHref = getPredictiveSearchItemUrl(product, { routes: routeTemplates, term });
+const querySuggestionHref = getPredictiveSearchItemUrl(querySuggestion, {
+  routes: routeTemplates,
+});
+```
+
+Pass `{term}` for resource items such as products, collections, pages, and articles. These items do not contain the shopper's typed search text, but the destination URL needs it for attribution. Do not pass `{term}` for `SearchQuerySuggestion` items; the helper uses `querySuggestion.text` automatically. Pass `{routes: routeTemplates}` so query suggestions honor a custom `search` route. Pass `{searchPath}` only when the suggestion link intentionally differs from the shared search route; it takes precedence when provided.
+
+If the storefront uses custom Shopify resource paths, use the local `hydrogen-routing` skill before wiring predictive search result URLs. Do not create predictive-search-only URL callbacks.
+
+Use `getSearchResultUrl()` only when constructing a custom search-attributed URL that is not backed by a predictive search item.
+
+Do not publish a new analytics event for predictive suggestions. Full search pages can keep their existing search-view analytics; predictive result links carry attribution through tracking parameters.
+
+## Custom Fragments
+
+Use additive fragments when the UI needs extra result fields:
+
+```ts
+import {
+  createPredictiveSearchServerHandlers,
+  gql,
+  makePredictiveSearchQueries,
+  queryPredictiveSearch,
+} from "@shopify/hydrogen";
+
+const predictiveSearchFragments = {
+  product: gql(`
+    fragment PredictiveSearchProductFragment on Product {
+      vendor
+    }
+  `),
+};
+
+const predictiveSearchHandlers = createPredictiveSearchServerHandlers({
+  fragments: predictiveSearchFragments,
+});
+
+const queries = makePredictiveSearchQueries({
+  fragments: predictiveSearchFragments,
+});
+
+const data = await queryPredictiveSearch({
+  storefrontClient,
+  term,
+  query: queries.predictiveSearch,
+});
+```
+
+Use the route-handler form for browser-backed autocomplete. Use `makePredictiveSearchQueries()` when querying directly from server code. Keep fragment names as documented by the API types. Hydrogen composes these with required base fields such as IDs, handles, titles, prices, images, and tracking parameters.
+
+## Rules
+
+- Use the packaged route handler as the default browser transport.
+- **Degrade to a normal search without JavaScript.** The search entry point must be a real `/search` link or a `role="search"` GET form, and the predictive modal's form must submit `GET /search` natively (`formProps()` defaults to this). Predictive autocomplete is an enhancement layered on top — never the only way to reach search results. With JS off, the trigger navigates to `/search` (or submits the term to it) and the full search page renders results server-side.
+- Keep UI rendering and layout app-owned.
+- Preserve `trackingParameters` on every predictive result link.
+- Use `q` for the search term so predictive and full search URLs align.
+- Use the local `hydrogen-routing` skill for result URLs when the app uses custom Shopify resource paths.
+- Render store errors near the search UI.
+- Keep debounce in the client store; do not add ad-hoc debounce in components unless there is a separate UX reason.
+- Prefer additive fragments over full query overrides.
+- Return empty UI for blank terms rather than querying Storefront API.
+- The modal is a native `<dialog>` opened with `showModal()`. For backdrop-dismiss, use `closedby="any"` where supported. For browsers without `closedby` support, use a pointerdown-plus-click guard: record whether `pointerdown` started on the dialog backdrop, then close only when the following `click` also targets the dialog. Do not close on a plain `click.self` alone — a drag that starts inside and ends on the backdrop can produce an accidental close.
+
+## Verify
+
+Done when:
+
+- [ ] Search works without JavaScript: a real `/search` link or `role="search"` GET form reaches server-rendered results, and the predictive modal's form submits `GET /search` natively.
+- [ ] Browser autocomplete goes through the same-origin `/api/predictive-search` route.
+- [ ] Every predictive result link preserves `trackingParameters` (built with `getPredictiveSearchItemUrl()`).
+- [ ] Blank terms render empty UI without querying the Storefront API.
+- [ ] Store errors surface near the search UI.
+- [ ] The search term uses `q` so predictive and full search URLs align.
+
+## Anti-patterns
+
+- Gating search behind JavaScript — a search trigger that only opens a JS autocomplete overlay, with no `/search` link or native GET form underneath, leaves no-JS shoppers with no way to search. The predictive layer must enhance a working `/search` path, not replace it.
+- Calling Storefront API directly from browser UI when a same-origin route can proxy the request.
+- Reusing `/search?predictive=true` as the autocomplete API when `/api/predictive-search` is available.
+- Dropping or manually concatenating tracking parameters.
+- Hard-coding predictive result links separately from the app's routing primitive.
+- Duplicating predictive search state in framework component state when the Hydrogen store already owns request lifecycle, debounce, aborts, and stale response handling.
+- Shipping a visual autocomplete component as the primary abstraction.

package/skills/hydrogen-predictive-search/references/react.md

@@ -0,0 +1,32 @@
+# React Predictive Search
+
+Wrap React search UI with the provider and render with hooks:
+
+```tsx
+import { PredictiveSearchProvider, usePredictiveSearch } from "@shopify/hydrogen/react";
+
+const PREDICTIVE_SEARCH_LIMIT = 5;
+
+function SearchAside() {
+  return (
+    <PredictiveSearchProvider limit={PREDICTIVE_SEARCH_LIMIT}>
+      <SearchInput />
+      <PredictiveResults />
+    </PredictiveSearchProvider>
+  );
+}
+
+function PredictiveResults() {
+  const { status, result, error } = usePredictiveSearch();
+
+  if (status === "loading") return <p>Loading…</p>;
+  if (status === "error") return <p role="alert">{error}</p>;
+  if (!result.total) return null;
+
+  return <ProductSuggestions products={result.items.products} term={result.term} />;
+}
+```
+
+Use `usePredictiveSearchActions()` for manual search/clear calls, or `usePredictiveSearchForm()` for headless form props and `register("query")` input props. `formProps()` defaults to native `GET /search` submission; override the provider's `searchAction` when the full search page lives elsewhere. Predictive search JSON requests use `predictiveSearchEndpoint` separately.
+
+Clear the store when closing an autocomplete overlay or navigating away from predictive results so stale suggestions do not reappear on reopen.

package/skills/hydrogen-predictive-search/references/vue.md

@@ -0,0 +1,40 @@
+# Vue Predictive Search
+
+Wrap Vue search UI with the provider and render with composables:
+
+```vue
+<script setup lang="ts">
+import {defineComponent, h} from "vue";
+import {PredictiveSearchProvider, usePredictiveSearch} from "@shopify/hydrogen/vue";
+
+const PREDICTIVE_SEARCH_LIMIT = 5;
+
+const PredictiveResults = defineComponent({
+  setup() {
+    const state = usePredictiveSearch();
+
+    return () => {
+      if (state.value.status === "loading") return h("p", "Loading...");
+      if (state.value.status === "error") return h("p", {role: "alert"}, state.value.error);
+      if (!state.value.result.total) return null;
+
+      return h(ProductSuggestions, {
+        products: state.value.result.items.products,
+        term: state.value.result.term,
+      });
+    };
+  },
+});
+</script>
+
+<template>
+  <PredictiveSearchProvider :limit="PREDICTIVE_SEARCH_LIMIT">
+    <SearchInput />
+    <PredictiveResults />
+  </PredictiveSearchProvider>
+</template>
+```
+
+Use `usePredictiveSearchActions()` for manual search/clear calls, or `usePredictiveSearchForm()` for headless form props and `register("query")` input props. `formProps()` defaults to native `GET /search` submission; override the provider's `searchAction` when the full search page lives elsewhere. Predictive search JSON requests use `predictiveSearchEndpoint` separately.
+
+Clear the store when closing an autocomplete overlay or navigating away from predictive results so stale suggestions do not reappear on reopen.

package/skills/hydrogen-request-handlers/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: hydrogen-request-handlers
+description: >
+  Guide for wiring Hydrogen request handlers in server frameworks. Use when
+  adding, modifying, or reviewing handleShopifyRoutes, handleShopifyRedirects,
+  SFAPI proxy routes, cart, predictive search, and Customer Account server handlers,
+  checkout redirects, cart permalinks, AJAX cart proxy routes, /admin redirects, Storefront URL redirects,
+  requestContext response-header propagation, or framework middleware,
+  not-found, and catch-all integration.
+---
+
+# Hydrogen Request Handlers
+
+Hydrogen request handlers are framework-neutral, but the framework wiring is not. Always choose the reference for the host framework and preserve its routing gate.
+
+## Framework References
+
+Before wiring middleware or route handlers, check whether this skill has a reference file for the app's framework in `references/`. If one exists, read it and preserve that framework's routing gate. If there is no matching reference, use `references/frameworks.md` as the generic adaptation guide and map its pre-routing and post-404 phases onto the app's server lifecycle.
+
+## Core Gate
+
+```
+Request
+  -> handleShopifyRoutes() before framework routing
+  -> framework router
+  -> handleShopifyRedirects() only after a 404
+  -> framework 404 page
+```
+
+`handleShopifyRoutes` owns Hydrogen routes the framework should never see: SFAPI proxy URLs, the generic `/__shopify/*` API proxy, `/checkout`, cart permalinks like `/cart/{variantId}:{quantity}`, AJAX cart URLs like `/cart.js` and `/cart/add.js`, `/api/mcp`, `/graphiql` in development, Liquid-style `?variant=<numeric id>` product URLs, and app-registered handler groups such as `createCartServerHandlers()` or `createCustomerAccountServerHandlers()`.
+
+## Variant Id Redirects
+
+```ts
+const shopifyRoute = handleShopifyRoutes({
+  request,
+  requestContext,
+  sessionManager,
+  storefrontClient,
+  routeTemplates,
+  handlers: [cartHandlers],
+});
+```
+
+Pass `routeTemplates` to `handleShopifyRoutes` so product `?variant=` links can be recognized before framework routing. `pathPrefix` is inferred from `requestContext.i18n.pathPrefix`, so localized product URLs stay in the localized tree.
+
+`handleShopifyRedirects` is a post-routing 404 check for `/admin`, configured standard route redirects, Storefront URL redirects, and same-origin query-param redirects. Do not run it on every request.
+
+## Standard Route Redirects
+
+Use the local `hydrogen-routing` skill to create the shared `routeTemplates` manifest. Wire that object into both `handleShopifyRoutes` before routing and `handleShopifyRedirects` after the app router returns a 404.
+
+```ts
+const redirect = await handleShopifyRedirects({
+  request,
+  storefrontClient,
+  routeTemplates,
+});
+```
+
+## Rules
+
+- Default to one request-scoped public Storefront client per request; `publicStorefrontToken` may be undefined for tokenless access (all mock.shop supports). Recommend a token-backed client once the app targets a real store, and upgrade to a private client when a private token and trusted buyer context exist.
+- Route handlers, cart server handlers, and `handleShopifyRedirects` accept any provided Storefront client.
+- When creating a private client, resolve trusted `buyerIp` first and pass it to `createShopifyRequestContext`. Use the `hydrogen-storefront-client` buyer-IP guidance for the app's deployment.
+- Create `requestContext` with `createShopifyRequestContext({ request, i18n, buyerIp })` where buyer context exists and the framework exposes a real `Request`; use `request: { headers }` only when no `Request` exists.
+- Pass the same request-scoped `requestContext`, `storefrontClient`, and `sessionManager` into `handleShopifyRoutes` and registered handler groups.
+- Call `handleShopifyRoutes` without awaiting it immediately. It returns `null` synchronously when no route matches; only return or await the promise after checking that it is truthy.
+- If the app has a request-level `try/catch` that converts errors into a `Response`, use `return await shopifyRoute` inside that boundary so rejected route promises reach the same error handling as synchronous setup failures. If the framework owns request error handling, return `shopifyRoute` directly. Do not add an inline `.catch()` unless the matched route intentionally needs different error handling.
+- Pass `request` and `storefrontClient` into `handleShopifyRedirects`; it does not receive a session manager.
+- Pass registered handler groups explicitly, for example `handlers: [cartHandlers, customerAccountHandlers]`.
+- Pass `routeTemplates` into `handleShopifyRoutes` so Liquid-parity `?variant=` product links resolve to canonical option params instead of passing through as ordinary product-page requests.
+- `handleShopifyRoutes` and `handleShopifyRedirects` apply request-context response headers before returning matched Shopify responses. Return those responses directly without calling `requestContext.applyResponseHeaders()` again.
+- Link and submit to Customer Account routes (`/account/login`, `/account/authorize`, `/account/refresh`, `/account/logout`) with plain HTML `<a>`/`<form>`, never the framework's client-side navigation component (`<Form>`/`<Link>` in React Router, `next/link` in Next.js, `NuxtLink` in Nuxt). The login and logout handlers return raw HTTP redirects to external Shopify URLs, which client-nav cannot process.
+- Apps authoring Customer Account API documents use the same packed Hydrogen TypeScript plugin as Storefront API documents. Add `@shopify/hydrogen/ts-plugin` to `tsconfig.json` `compilerOptions.plugins` and chain `hydrogen gql check` into a package script. Applies to every framework.
+- For custom or framework-routed responses, commit session headers once at the final response boundary, append those headers, then call `requestContext.applyResponseHeaders(response.headers)` so SFAPI cookies, `Server-Timing`, tracking fallback headers, and personalized-response cache safety survive.
+- Wire this in production runtime code, not dev-only hooks. Only GraphiQL is dev-only.
+
+## Imports
+
+Use public package exports:
+
+```ts
+import {
+  createCartServerHandlers,
+  createPredictiveSearchServerHandlers,
+  createShopifyRequestContext,
+  createStorefrontClient,
+  handleShopifyRedirects,
+  handleShopifyRoutes,
+} from "@shopify/hydrogen";
+import { createCustomerAccountServerHandlers } from "@shopify/hydrogen/customer-account";
+```
+
+## Verify
+
+Run the app in dev and production modes, then check:
+
+1. `POST /api/{api-version}/graphql.json` returns Storefront API JSON, not the app 404.
+2. `GET /api/cart` returns cart handler JSON when cart handlers are registered. With no cart id, the body is `{cart: null}` and no Storefront API cart lookup is made.
+3. `GET /api/predictive-search?q=snow` returns predictive search JSON when predictive search handlers are registered.
+4. `GET /account/login`, `GET /account/authorize`, `GET /account/refresh`, and `POST /account/logout` are handled before the app router when Customer Account handlers are registered.
+5. `GET /admin` returns a redirect to the shop admin URL.
+6. An unknown path returns the framework 404 when no Shopify redirect exists.
+7. `GET /products/{handle}?variant={numeric id}` returns a 302 to the option-params URL when `routeTemplates` is passed to `handleShopifyRoutes`; `?variant=garbage` falls through to the product page.
+8. Cart, predictive search, Customer Account, and SFAPI responses preserve `Set-Cookie` and `Server-Timing` headers where the framework exposes them.
+9. Authenticated Customer Account responses do not preserve public or CDN cache-control headers.