@shopify/hydrogen 2026.4.5 → 2026.10.0-preview.2

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,142 @@
+---
+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.
+
+## Certificates
+
+The `localHttps` Vite plugin provisions missing certificates automatically when `vite dev` starts: it downloads a pinned, checksum-verified [mkcert](https://github.com/FiloSottile/mkcert) release, installs the local certificate authority (this may prompt for your password), and generates the certificate files under `~/.shopify/hydrogen/certs/`. To provision ahead of time — or for frameworks that read certificate paths before Vite starts (Nuxt, SolidStart) — run:
+
+```sh
+npx hydrogen certs install
+```
+
+Remove Hydrogen's generated certificate files and cached mkcert binary with `npx hydrogen certs uninstall`. This leaves mkcert's shared local certificate authority trusted because other projects may use it. Pass `--remove-ca` to remove that shared CA from the system trust stores too.
+
+Pass `certPath` and `keyPath` to use another location. When automatic download is unavailable for a platform, install mkcert manually and generate the files at the paths the warning prints.
+
+The plugin skips automatic provisioning when the `CI` environment variable is set, because installing the certificate authority needs an interactive trust prompt. Run `npx hydrogen certs install` explicitly when a CI job genuinely needs local HTTPS.
+
+## Vite
+
+```ts
+import { localHttps } from "@shopify/hydrogen/vite";
+import { defineConfig } from "vite";
+
+const httpsOptions = {
+  enabled: process.env.npm_lifecycle_event === "dev:https" || process.env.VITE_LOCAL_HTTPS === "1",
+};
+
+export default defineConfig({
+  plugins: [localHttps(httpsOptions)],
+});
+```
+
+Start Vite through a `dev:https` package script. A normal `vite dev` remains plain HTTP.
+
+```json
+{
+  "scripts": {
+    "dev": "vite dev",
+    "dev:https": "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 === "dev:https" || 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. Nitro reads the paths when the config is evaluated, so provision certificates with `npx hydrogen certs install` (or restart once after the plugin provisions them):
+
+```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 === "dev:https" || 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 and reads certificate paths when the config is evaluated, so provision certificates with `npx hydrogen certs install` (or restart once after the plugin provisions them):
+
+```ts
+import { defineConfig } from "@solidjs/start/config";
+import { localHttps } from "@shopify/hydrogen/vite";
+
+const httpsOptions = {
+  enabled: process.env.npm_lifecycle_event === "dev:https" || 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": {
+    "dev:https": "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.

package/skills/hydrogen-markets/SKILL.md

@@ -0,0 +1,221 @@
+---
+name: hydrogen-markets
+description: >
+  Guide for implementing Shopify Markets with Hydrogen. Use when adding
+  market routing, country/language localization, Shopify Markets, subdomains,
+  per-market domains, path-prefixed markets, Next.js App Router market routing,
+  or Storefront API @inContext wiring.
+---
+
+# Markets
+
+Markets are an application routing concern plus Storefront API context. Hydrogen does not prescribe how a storefront chooses a market. Use domains, subdomains, paths, cookies, buyer preferences, geolocation, or merchant config as needed.
+
+The Hydrogen part is request-scoped `i18n` on `createShopifyRequestContext`. Resolve the market first, then create the request context with `i18n`. When a query declares `$country` and `$language` and uses `@inContext(country: $country, language: $language)`, the client injects those values from the resolved `i18n`.
+
+If the storefront uses Next.js App Router, read `references/nextjs.md` before writing code. Server Components do not receive a full `Request`, so host-based and path-prefixed markets need Next-specific wiring.
+
+---
+
+## Core Rule
+
+Add `i18n` where the app already creates its Shopify request context:
+
+```diff
+import {
+  createStorefrontClient,
+  createShopifyRequestContext,
+  gql,
+} from "@shopify/hydrogen";
+
+const PRODUCTS_PAGE_SIZE = 12;
+
+const PRODUCTS_QUERY = gql(`
+-  query Products($first: Int!) {
++  query Products($first: Int!, $country: CountryCode, $language: LanguageCode)
++  @inContext(country: $country, language: $language) {
+    products(first: $first) {
+      nodes {
+        title
+      }
+    }
+  }
+`);
+
+export async function loadProducts(request: Request) {
+-  const requestContext = createShopifyRequestContext({
+-    request,
+-    i18n: DEFAULT_MARKET,
+-  });
++  const i18n = getMarketFromRequest(request);
++  const requestContext = createShopifyRequestContext({
++    request,
++    i18n,
++  });
+
+  const client = createStorefrontClient({
+    type: "public",
+    requestContext,
+    config: {
+      storeDomain: process.env.PUBLIC_STORE_DOMAIN!,
+      publicStorefrontToken: process.env.PUBLIC_STOREFRONT_API_TOKEN!,
+    },
+  });
+
+  return client.graphql(PRODUCTS_QUERY, {
+    variables: { first: PRODUCTS_PAGE_SIZE },
+  });
+}
+```
+
+Do not pass `country` or `language` in every query call. Resolve the market once at the request boundary, set `i18n` when creating the request context, and let the client inject the context variables into queries that declare them.
+
+The returned Storefront client exposes the resolved locale as `client.i18n`. Use `client.i18n.pathPrefix` when app route helpers need to prepend a market path; Hydrogen normalizes it to `""` or a leading-slash prefix with no trailing slash.
+
+---
+
+## Market Shape
+
+Keep the resolver small and explicit. The Storefront API expects uppercase enum values like `US`, `CA`, `EN`, and `FR`.
+
+```ts
+type Market = {
+  country: string;
+  language: string;
+  pathPrefix?: string;
+};
+
+const DEFAULT_MARKET = {
+  country: "US",
+  language: "EN",
+} satisfies Market;
+```
+
+If the app needs labels or alternate domains, keep those as application fields. `country` and `language` are required in `i18n`; `pathPrefix` is optional on input and is normalized on the request context to `""` or a leading-slash prefix with no trailing slash.
+
+---
+
+## Subdomains
+
+Use this when each market lives under one storefront domain, like `ca.example.com` or `fr.example.com`.
+
+```ts
+const MARKET_BY_SUBDOMAIN = {
+  ca: { country: "CA", language: "EN" },
+  fr: { country: "FR", language: "FR" },
+} satisfies Record<string, Market>;
+
+export function getMarketFromRequest(request: Request): Market {
+  const { hostname } = new URL(request.url);
+  const [subdomain] = hostname.toLowerCase().split(".");
+
+  return MARKET_BY_SUBDOMAIN[subdomain] ?? DEFAULT_MARKET;
+}
+```
+
+---
+
+## Per-Market Domains
+
+Use this when markets have separate buyer-facing domains, like `example.com`, `example.ca`, and `example.fr`.
+
+```ts
+const MARKET_BY_HOST = {
+  "example.com": { country: "US", language: "EN" },
+  "example.ca": { country: "CA", language: "EN" },
+  "example.fr": { country: "FR", language: "FR" },
+} satisfies Record<string, Market>;
+
+export function getMarketFromRequest(request: Request): Market {
+  const { hostname } = new URL(request.url);
+  const host = hostname.toLowerCase();
+
+  return MARKET_BY_HOST[host] ?? DEFAULT_MARKET;
+}
+```
+
+---
+
+## Path Prefixes
+
+Use this when markets share one domain and the market is encoded in the pathname, like `/en-ca/products/shirt` or `/fr-fr/products/shirt`.
+
+```ts
+type PathMarket = Market & {
+  pathPrefix: string;
+};
+
+const FIRST_PATH_SEGMENT_INDEX = 0;
+
+const MARKET_BY_PATH_PREFIX = {
+  "en-ca": { country: "CA", language: "EN", pathPrefix: "/en-ca" },
+  "fr-fr": { country: "FR", language: "FR", pathPrefix: "/fr-fr" },
+} satisfies Record<string, PathMarket>;
+
+function getFirstPathSegment(pathname: string): string | undefined {
+  return pathname.split("/").filter(Boolean)[FIRST_PATH_SEGMENT_INDEX];
+}
+
+export function getMarketFromRequest(request: Request): PathMarket | Market {
+  const { pathname } = new URL(request.url);
+  const pathPrefix = getFirstPathSegment(pathname);
+
+  if (!pathPrefix) return DEFAULT_MARKET;
+
+  return MARKET_BY_PATH_PREFIX[pathPrefix.toLowerCase()] ?? DEFAULT_MARKET;
+}
+
+export function localizePath(pathname: string, market: PathMarket | Market): string {
+  if (!("pathPrefix" in market)) return pathname;
+
+  const normalizedPathname = pathname.replace(/^\/+/, "");
+  return `${market.pathPrefix}/${normalizedPathname}`;
+}
+```
+
+The router should strip or interpret the prefix before matching product and collection routes. Hydrogen's Storefront API variable injection uses `country` and `language`; `pathPrefix` is carried as a leading-slash app route prefix for helpers.
+
+When the app uses custom Shopify resource paths, use the local `hydrogen-routing` skill. Keep market prefixes in `i18n.pathPrefix`, not in route template values.
+
+---
+
+## Framework Exceptions
+
+Read the relevant reference before applying the generic `Request` examples in frameworks that do not expose the full incoming request to server code.
+
+- **Next.js App Router** — read `references/nextjs.md` first. Server Components can read `headers()` and route `params`, but not the current URL or a standard `Request`; host-based markets, path-prefix markets, and raw URL fallback each need different wiring.
+
+---
+
+## Rules
+
+- **Use whatever market strategy fits the store.** Hydrogen should not force domains, subdomains, pathnames, or detection policy.
+- **Resolve the market on the server from a standard `Request`.** `new URL(request.url)` is enough for host and path strategies.
+- **Use request-context `i18n` as the Storefront API boundary.** Prefer `createShopifyRequestContext({ request, i18n })`. Always provide a default market rather than letting it be undefined.
+- **Use market-contextualized queries.** The Storefront client injects `country` and `language` variable values when the document declares `$country` and `$language`; it does not rewrite query text. Market-sensitive queries still need `@inContext(country: $country, language: $language)` or equivalent Storefront API context in the document.
+- **Do not calculate currency locally.** Render `amount` and `currencyCode` returned by Shopify and format them with the local `hydrogen-money` skill's `formatMoney()` guidance.
+- **Keep ShopifyScripts in the same market.** When the app renders Shopify browser runtime scripts, pass the resolved `country` and `language` into `ShopifyScripts` i18n so Shopify globals match Storefront API context.
+- **Keep route templates prefix-free.** When route templates are configured, pass market prefixes through `i18n.pathPrefix`; do not bake prefixes such as `/en-ca` into template values.
+- **Keep translations separate.** Shopify Markets context localizes Shopify data. Application UI strings still need the app's translation system.
+- **Treat geolocation as a hint, not truth.** Buyers travel, use VPNs, and intentionally choose markets. Persist explicit choices when the app supports switching.
+- **Ask before choosing the strategy.** If the app does not already make market selection clear, ask whether domains, subdomains, path prefixes, cookies, buyer preference, geolocation, or merchant config should own it before writing code.
+
+---
+
+## Testing
+
+Test market resolution with plain `Request` objects. You do not need a framework test harness.
+
+```ts
+import { describe, expect, it } from "vitest";
+
+describe("getMarketFromRequest", () => {
+  it("resolves a subdomain market", () => {
+    const request = new Request("https://ca.example.com/products/shirt");
+
+    expect(getMarketFromRequest(request)).toEqual({ country: "CA", language: "EN" });
+  });
+});
+```
+
+Also test at least one Storefront API call through a mocked fetch and assert the GraphQL variables include the expected `country` and `language` when the query declares them.