@shopify/hydrogen 2026.4.4 → 2026.10.0-preview.1

package/skills/hydrogen-collection-browser/references/react.md

@@ -0,0 +1,237 @@
+# React And React Router
+
+## Contents
+
+- Loader
+- Provider
+- Browse Form
+- Filters
+- Search Pages
+
+Use the React binding:
+
+```tsx
+import {
+  getFilterRemovalUrl,
+  getSortByValue,
+  isFilterInputActive,
+  parseCollectionParams,
+  serializeCollectionParams,
+  type AvailableFilter,
+  type CollectionState,
+  type ProductFilter,
+} from "@shopify/hydrogen";
+import { CollectionProvider, useCollection, useCollectionForm } from "@shopify/hydrogen/react";
+import type { ProductFilter as StorefrontApiProductFilter } from "@shopify/hydrogen/storefront-api-types";
+```
+
+Use `getSortByValue(...)` for option values so the `sort_by` query param round-trips through `parseCollectionParams()`:
+
+```ts
+const COLLECTION_SORT_OPTIONS = [
+  { label: "Featured", value: getSortByValue("COLLECTION_DEFAULT", false) },
+  { label: "Best selling", value: getSortByValue("BEST_SELLING", false) },
+  { label: "Alphabetically, A-Z", value: getSortByValue("TITLE", false) },
+  { label: "Alphabetically, Z-A", value: getSortByValue("TITLE", true) },
+  { label: "Price, low to high", value: getSortByValue("PRICE", false) },
+  { label: "Price, high to low", value: getSortByValue("PRICE", true) },
+  { label: "Date, old to new", value: getSortByValue("CREATED", false) },
+  { label: "Date, new to old", value: getSortByValue("CREATED", true) },
+];
+
+const SEARCH_SORT_OPTIONS = [
+  { label: "Relevance", value: getSortByValue("RELEVANCE", false) },
+  { label: "Price, low to high", value: getSortByValue("PRICE", false) },
+  { label: "Price, high to low", value: getSortByValue("PRICE", true) },
+];
+```
+
+## Loader
+
+In a route loader, parse the current URL and query the Storefront API with the parsed browse state:
+
+```ts
+export async function loader({ context, params, request }: Route.LoaderArgs) {
+  const storefrontClient = context.get(storefrontClientContext);
+  const url = new URL(request.url);
+  const browse = parseCollectionParams(url.searchParams);
+
+  const { data } = await storefrontClient.graphql(COLLECTION_QUERY, {
+    variables: {
+      handle: params.handle,
+      first: 24,
+      filters:
+        browse.filters.length > 0 ? (browse.filters as StorefrontApiProductFilter[]) : undefined,
+      sortKey: browse.sortKey,
+      reverse: browse.reverse || undefined,
+    },
+  });
+
+  if (!data?.collection) throw new Response("Collection not found", { status: 404 });
+
+  return {
+    collection: data.collection,
+    products: data.collection.products.nodes,
+    availableFilters: data.collection.products.filters,
+    dataSearch: url.searchParams.toString(),
+  };
+}
+```
+
+Keep `dataSearch` exactly aligned with the query used for the server data.
+
+## Provider
+
+Wrap the browse UI in `CollectionProvider` and let it own filter/sort intent:
+
+```tsx
+export default function CollectionRoute({ loaderData }: Route.ComponentProps) {
+  const navigate = useNavigate();
+  const [searchParams] = useSearchParams();
+
+  return (
+    <CollectionProvider
+      data={{ handle: loaderData.collection.handle, dataSearch: loaderData.dataSearch }}
+      urlSearch={searchParams.toString()}
+      onChange={(search) =>
+        navigate(
+          { search },
+          {
+            replace: searchParams.size > 0,
+            preventScrollReset: true,
+          },
+        )
+      }
+    >
+      <CollectionPage {...loaderData} />
+    </CollectionProvider>
+  );
+}
+```
+
+## Browse Form
+
+Inside the browse UI:
+
+```tsx
+function CollectionPage({ availableFilters, products }: Props) {
+  const state = useCollection();
+  const { formProps } = useCollectionForm();
+  const isLoading = state.status === "loading";
+
+  return (
+    <form {...formProps()} method="get" action={collectionPath} className="browse">
+      <FilterSidebar
+        availableFilters={availableFilters}
+        activeFilters={state.filters}
+        disabled={isLoading}
+      />
+      <select name="sort_by" defaultValue={currentSortValue(state)} onChange={requestFormSubmit}>
+        {COLLECTION_SORT_OPTIONS.map((option) => (
+          <option key={option.label} value={option.value}>
+            {option.label}
+          </option>
+        ))}
+      </select>
+      <ProductGrid products={products} pending={isLoading} />
+    </form>
+  );
+}
+
+function requestFormSubmit(event: React.ChangeEvent<HTMLInputElement | HTMLSelectElement>) {
+  event.currentTarget.form?.requestSubmit();
+}
+```
+
+Pass `method="get"` and an explicit `action={collectionPath}` (the current `/collections/:handle` or `/search` route URL) literally — `formProps()` only wires the submit handler (see the SKILL.md UI rule).
+
+Use uncontrolled form controls. When a route needs to remount checkboxes after external navigation, put `key={serializeCollectionParams({ filters: state.filters, sortKey: undefined, reverse: false }).toString()}` on the filter subtree (for search, include the term in the key) — keyed by serialized **filter state**, not the live URL. The URL clears before the `CollectionProvider` reconciler settles `state.filters`, so a URL-keyed remount bakes in stale `defaultChecked`. This resets checkbox DOM state without coupling active filter chips to the form remount.
+
+## Filters
+
+For each Storefront `FilterValue`, treat `value.input` as the canonical JSON-encoded `ProductFilter`. Convert it to checkbox params by parsing the JSON, wrapping it in the minimal collection state shape, and calling `serializeCollectionParams(...)`. Use Hydrogen helpers for active checks:
+
+```tsx
+function filterValueInputParamEntries(input: string): Array<{ name: string; value: string }> {
+  let filter: ProductFilter;
+  try {
+    filter = JSON.parse(input) as ProductFilter;
+  } catch {
+    return [];
+  }
+
+  return Array.from(
+    serializeCollectionParams({ filters: [filter], sortKey: undefined, reverse: false }),
+    ([name, value]) => ({ name, value }),
+  );
+}
+
+function FilterValueInput({ activeFilters, filter, value }: Props) {
+  const entries = filterValueInputParamEntries(value.input);
+  if (entries.length !== 1) return null;
+
+  const [{ name, value: paramValue }] = entries;
+
+  return (
+    <input
+      type="checkbox"
+      name={name}
+      value={paramValue}
+      defaultChecked={isFilterInputActive(activeFilters, value.input)}
+      onChange={(event) => {
+        if (isMutuallyExclusive(filter) && event.currentTarget.checked) {
+          uncheckSiblings(event.currentTarget);
+        }
+        requestFormSubmit(event);
+      }}
+    />
+  );
+}
+```
+
+`filterValueInputParamEntries` is app glue code, not a Hydrogen export. Its body should stay this thin: `JSON.parse(value.input)` plus `serializeCollectionParams(...)`. Do not replace it with a custom mapping table for availability, product type, vendor, tags, options, metafields, or price. The app should not create its own `ProductFilter` from `filter.id`, `filter.label`, `filter.type`, `value.id`, or display labels; those are UI metadata, not the Storefront API filter contract.
+
+For active chips, use parsed active `ProductFilter` values from collection state:
+
+```tsx
+function ActiveFilterChip({ collectionPath, filter, state }: Props) {
+  const currentParams = serializeCollectionParams(state);
+  const removal = getFilterRemovalUrl(currentParams, filter);
+  const href = removal === "?" ? collectionPath : `${collectionPath}${removal}`;
+
+  return (
+    <a href={href}>
+      {describeFilter(filter)}
+    </a>
+  );
+}
+```
+
+When passing `browse.filters` into a `gql()` query variable typed from Storefront API introspection, match the app's established pattern. The Hydrogen examples cast the parsed filters to the generated Storefront API `ProductFilter` type at the query variable boundary:
+
+```ts
+import type { ProductFilter as StorefrontApiProductFilter } from "@shopify/hydrogen/storefront-api-types";
+
+variables: {
+  filters:
+    browse.filters.length > 0 ? (browse.filters as StorefrontApiProductFilter[]) : undefined,
+}
+```
+
+Keep this as a generated-type cast scoped to the query variable boundary.
+
+## Search Pages
+
+Use the same binding with a synthetic handle:
+
+```tsx
+<CollectionProvider
+  data={{ handle: `search:${term}`, dataSearch }}
+  urlSearch={searchParams.toString()}
+  onChange={(search) => navigate({ search }, { replace: searchParams.size > 0 })}
+>
+  <input type="hidden" name="q" value={term} />
+</CollectionProvider>
+```
+
+When the search term changes, include it in the browse form `key` so old unchecked/checked inputs do not carry over.

package/skills/hydrogen-customer-account/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: hydrogen-customer-account
+description: >
+  Customer Account API setup for Hydrogen storefronts. Use when wiring customer
+  sessions, login/logout/OAuth route handlers, account profile, order history,
+  account-gated UI, cart buyer identity sync, or Customer Account
+  GraphQL queries.
+---
+
+# Customer Account API
+
+The Customer Account API powers login, account profile, order history, and account-gated UI. Hydrogen provides typed GraphQL helpers and OAuth/session primitives; the app still owns framework integration, UI, and session storage.
+
+## Configuration
+
+Use server-side configuration for:
+
+- `SHOP_ID` — numeric Shopify shop ID string. Do not use a Shop GID or shop domain.
+- `PUBLIC_CUSTOMER_ACCOUNT_API_CLIENT_ID` — Customer Account API client ID.
+- `CUSTOMER_ACCOUNT_SESSION_SECRET` — private per-app secret for encrypted cookie examples, or replace cookie storage with opaque server-side sessions in production.
+
+Do not expose access tokens, refresh tokens, ID tokens, or session secrets to client components or browser storage.
+
+## Session Module
+
+Create `customerSession` at module scope with `createCustomerSession({ shopId, customerAccountApiClientId })`. Create request-scoped session managers from the framework request, backed by protected server storage or encrypted HttpOnly cookies.
+
+Use the same `requestContext` for Storefront and Customer Account work in a request. Customer Account reads and GraphQL calls mark responses personalized so final response headers must run through `requestContext.applyResponseHeaders()`.
+
+Expose two app-owned session-manager helpers when the framework has both read-only render paths and writable response boundaries:
+
+- Read-only helpers return or accept `ReadonlyCustomerSessionManager`. Use them in Server Components, layouts, loaders, and account header UI.
+- Writable helpers return or accept `WritableCustomerSessionManager`. Use them only where the returned response can commit `Set-Cookie`, such as Hydrogen route handlers, route handlers, server functions, middleware/proxy responses, or framework finalizers.
+
+This makes the dangerous path harder to hold wrong: TypeScript rejects `customerSession.getOrRefreshAccessToken()` when the caller only has a `ReadonlyCustomerSessionManager`.
+
+## Route Wiring
+
+Register `createCustomerAccountServerHandlers({ customerSession })` with the app's `handleShopifyRoutes` setup.
+
+## Cart Buyer Identity Sync
+
+To keep the browser cart's buyer identity in step with the customer session, create the cart handlers with the same `customerSession` and pass them to the Customer Account handlers:
+
+```ts
+import { createCartServerHandlers } from "@shopify/hydrogen";
+import { createCustomerAccountServerHandlers } from "@shopify/hydrogen/customer-account";
+
+const cartHandlers = createCartServerHandlers({ customerSession });
+
+const customerAccountHandlers = createCustomerAccountServerHandlers({
+  customerSession,
+  cartServerHandlers: cartHandlers,
+});
+```
+
+With this wiring, Hydrogen owns the whole loop:
+
+- New carts are created with the current customer's buyer identity when the session has a usable access token or successfully refreshed access token, and authenticated cart reads mark checkout URLs with `logged_in=true` (from the cart handlers' `customerSession` option).
+- Authorization and refresh attach the customer to the cart from the request's cart cookie; a definitive refresh rejection detaches it. Transient refresh failures leave the cart untouched.
+- Logout detaches the customer from the cart.
+
+Sync is best-effort: a failed cart mutation never blocks the route's redirect. Attach failures are logged and can be retried by a later refresh. If detach fails during logout or definitive refresh rejection, the handler expires the cart cookie so a shared device never keeps a cart bound to the previous customer.
+
+`cartServerHandlers` requires both handler groups to share the `customerSession` returned by `createCustomerSession`; TypeScript rejects cart handlers created without `customerSession`.
+
+The Customer Account handlers own:
+
+- `GET /account/login`
+- `GET /account/authorize`
+- `GET /account/refresh`
+- `POST /account/logout`
+
+Do not reimplement login, authorize, refresh, or logout unless the app needs custom behavior that preserves the same safeguards: sanitized `return_to`, same-origin logout POST checks, `cache-control: no-store`, committed session cookies on the returned response, and request-context response headers.
+
+## Server Rendering
+
+Server-rendered account UI must keep session reads and token refresh separate:
+
+- Use `customerSession.isLoggedIn()` for read-only signed-in UI such as an account link. It treats a refreshable session as logged in without refreshing tokens.
+- Use `customerSession.getAccessToken()` before Customer Account GraphQL calls. It returns only a currently usable access token.
+- If `isLoggedIn()` is true but `getAccessToken()` returns `undefined`, redirect once to `/account/refresh?return_to=...` from a dynamic server route, then retry the account page after the refresh route commits cookies.
+- If `isLoggedIn()` is false, show login UI or redirect to `/account/login` instead of sending the user to `/account/refresh`.
+- Include a one-shot refresh guard in `return_to`; if the refreshed page still has no usable access token, fall back to login or an account error state.
+- Server Components and layouts should only receive `ReadonlyCustomerSessionManager`, so they cannot call `getOrRefreshAccessToken()`.
+
+Wrap header/account-link UI in the framework's streaming primitive when possible so the shell can render before session state resolves.
+
+## Account Page
+
+Hydrogen ships no account UI yet — the app owns it. A storefront with the handlers wired but no account page has working auth endpoints a buyer can never reach. Build at least a minimal `/account` route:
+
+- **Signed out** — render a sign-in panel linking to `/account/login?return_to=/account`. The login link must be a full-document navigation (plain `<a>` or the framework link's reload-document mode): the handler returns a raw redirect to Shopify's hosted login page that client-side routing cannot follow.
+- **Signed in** — fetch and render a minimal profile (`customer { firstName lastName emailAddress { emailAddress } }`). Check GraphQL `errors` and render an error state instead of crashing.
+- **Logout** — a plain HTML `<form method="post" action="/account/logout">` with a submit button. The handler enforces same-origin POST and returns a raw redirect (to Shopify's logout endpoint when an `id_token` exists); a native browser submit follows it, a client-side form component or fetch call does not. This also keeps logout working without JavaScript. An optional `return_to` search param on the action URL controls the post-logout destination.
+- **Navbar** — link to `/account`. A static link is enough; the page handles both states. If showing signed-in state in the header, use `isLoggedIn()` behind the framework's streaming primitive per the Server Rendering rules above.
+- Never serialize tokens or session objects into loader data or HTML; render only derived profile fields.
+
+## Typed Queries
+
+Use `gql` and `createCustomerAccountClient` from `@shopify/hydrogen/customer-account` in server code only. Pass the access token per GraphQL call.
+
+The same `@shopify/hydrogen/ts-plugin` and `hydrogen gql check` setup from the `hydrogen-storefront-client` skill validates Customer Account API documents too. If the check is not already chained into the app's `typecheck` package script, add it there (create the script if the app has none), then run it before treating setup as complete — framework typecheck commands do not validate `gql()` documents on their own.
+
+## Local OAuth
+
+Customer Account OAuth needs a public HTTPS callback origin. For local examples, use a trusted local HTTPS hostname and register the exact `/account/authorize` callback URL in the Customer Account app configuration.

package/skills/hydrogen-image/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: hydrogen-image
+description: >
+  Helper-only sizing of Shopify CDN image URLs. Use when rendering Storefront
+  API images in product/collection cards, PDP galleries, PLP heroes, cart
+  thumbnails, or other img element surfaces.
+---
+
+# Hydrogen Image Sizing
+
+Hydrogen ships no Image component. Size Shopify CDN image URLs with a tiny local helper and render plain `<img>`.
+
+## Param contract
+
+CDN sizing params (`width`, `height`, `crop`, plus format/scale/no-upscale) are documented by Shopify — Storefront API `ImageTransformInput`: https://shopify.dev/docs/api/storefront/latest/input-objects/ImageTransformInput
+
+## The 3 rules
+
+1. **Host allowlist.** Only rewrite `cdn.shopify.com` / `mock.shop` and their subdomains. Pass third-party images through unchanged (e.g. an Unsplash hero with its own `w=`).
+2. **`mock.shop` counts as a Shopify CDN host.**
+3. **Append params with `URL.searchParams`** to preserve any existing query string — never string-concat.
+
+## Helper
+
+```ts
+type ShopifyImageOptions = {
+  width?: number;
+  height?: number;
+  crop?: "center" | "top" | "bottom" | "left" | "right";
+};
+
+const SHOPIFY_CDN_HOSTS = ["cdn.shopify.com", "mock.shop"];
+
+function isShopifyImageHost(hostname: string) {
+  return SHOPIFY_CDN_HOSTS.some((host) => hostname === host || hostname.endsWith(`.${host}`));
+}
+
+export function shopifyImageUrl(url: string, options: ShopifyImageOptions = {}) {
+  let parsed: URL;
+  try {
+    parsed = new URL(url);
+  } catch {
+    return url;
+  }
+
+  if (!isShopifyImageHost(parsed.hostname)) return url;
+
+  if (options.width) parsed.searchParams.set("width", String(options.width));
+  if (options.height) parsed.searchParams.set("height", String(options.height));
+  if (options.crop) parsed.searchParams.set("crop", options.crop);
+
+  return parsed.toString();
+}
+
+export function srcSetFor(url: string, options: ShopifyImageOptions) {
+  const oneX = shopifyImageUrl(url, options);
+  const twoX = shopifyImageUrl(url, {
+    ...options,
+    width: options.width ? options.width * 2 : undefined,
+    height: options.height ? options.height * 2 : undefined,
+  });
+
+  return `${oneX} 1x, ${twoX} 2x`;
+}
+```

package/skills/hydrogen-local-https/SKILL.md

@@ -0,0 +1,144 @@
+---
+name: hydrogen-local-https
+description: >
+  Configure trusted local HTTPS for Customer Account API development with
+  Vite-based frameworks or Next.js.
+---
+
+# Local HTTPS
+
+Customer Account login, logout, and OAuth callbacks require an HTTPS, non-`localhost` origin that exactly matches the URLs registered in Shopify admin. `local.tryhydrogen.dev` is a Shopify-owned domain that resolves publicly to `127.0.0.1`, so it provides a stable local hostname.
+
+## Vite Certificate Setup
+
+Vite-based frameworks need manual certificates until automatic provisioning is available. Install and trust [mkcert](https://github.com/FiloSottile/mkcert), then create the default certificate files:
+
+```sh
+brew install mkcert
+mkcert -install
+mkdir -p ~/.shopify/hydrogen/certs
+mkcert \
+  -cert-file ~/.shopify/hydrogen/certs/local.tryhydrogen.dev.pem \
+  -key-file ~/.shopify/hydrogen/certs/local.tryhydrogen.dev-key.pem \
+  local.tryhydrogen.dev
+```
+
+Pass `certPath` and `keyPath` to use another location. Certificate generation is intentionally separate from the plugin.
+
+## Vite
+
+```ts
+import { localHttps } from "@shopify/hydrogen/vite";
+import { defineConfig } from "vite";
+
+const httpsOptions = {
+  enabled: process.env.npm_lifecycle_event === "https:dev" || process.env.VITE_LOCAL_HTTPS === "1",
+};
+
+export default defineConfig({
+  plugins: [localHttps(httpsOptions)],
+});
+```
+
+Start Vite through an `https:dev` package script. A normal `vite dev` remains plain HTTP.
+
+```json
+{
+  "scripts": {
+    "dev": "vite dev",
+    "https:dev": "vite dev"
+  }
+}
+```
+
+## Astro
+
+Astro needs its own host and port in addition to the Vite plugin:
+
+```js
+import { LOCAL_HTTPS_DEFAULTS, localHttps } from "@shopify/hydrogen/vite";
+import { defineConfig } from "astro/config";
+
+const enabled = process.env.npm_lifecycle_event === "https:dev" || process.env.VITE_LOCAL_HTTPS === "1";
+const httpsOptions = { enabled };
+
+export default defineConfig({
+  server: enabled
+    ? { host: LOCAL_HTTPS_DEFAULTS.host, port: LOCAL_HTTPS_DEFAULTS.port }
+    : undefined,
+  vite: { plugins: [localHttps(httpsOptions)] },
+});
+```
+
+## Nuxt
+
+Nitro terminates TLS, so provide certificate paths to both Nitro and Vite:
+
+```ts
+import { localHttps } from "@shopify/hydrogen/vite";
+import type { NuxtConfig } from "nuxt/schema";
+
+type VitePlugin = NonNullable<NonNullable<NuxtConfig["vite"]>["plugins"]>[number];
+
+const httpsOptions = {
+  enabled: process.env.npm_lifecycle_event === "https:dev" || process.env.VITE_LOCAL_HTTPS === "1",
+};
+const httpsPlugin = localHttps(httpsOptions);
+
+export default defineNuxtConfig({
+  devServer: httpsPlugin.api.getDevServerConfig(),
+  vite: {
+    plugins: [httpsPlugin as VitePlugin],
+  },
+});
+```
+
+## SolidStart/Vinxi
+
+Vinxi terminates TLS outside Vite:
+
+```ts
+import { defineConfig } from "@solidjs/start/config";
+import { localHttps } from "@shopify/hydrogen/vite";
+
+const httpsOptions = {
+  enabled: process.env.npm_lifecycle_event === "https:dev" || process.env.VITE_LOCAL_HTTPS === "1",
+};
+const httpsPlugin = localHttps(httpsOptions);
+const devServer = httpsPlugin.api.getDevServerConfig();
+
+export default defineConfig({
+  server: { https: devServer?.https },
+  vite: { plugins: [httpsPlugin] },
+});
+```
+
+Vinxi also needs its bind target and port on startup:
+
+```json
+{
+  "scripts": {
+    "https:dev": "vinxi dev --host local.tryhydrogen.dev --port 5173"
+  }
+}
+```
+
+## Next.js
+
+Next.js provisions its own trusted certificate:
+
+```sh
+next dev --experimental-https --hostname local.tryhydrogen.dev --port 5173
+```
+
+## Shopify Admin
+
+In the Hydrogen or Headless sales channel, open the storefront's **Customer Account API settings** and configure:
+
+```text
+Callback URI(s):       https://local.tryhydrogen.dev:5173/account/authorize
+JavaScript origin(s):  https://local.tryhydrogen.dev
+Logout URI:            https://local.tryhydrogen.dev:5173
+```
+
+The JavaScript origin intentionally has no port. Shopify's server-side validation rejects JavaScript origins containing a port.