@shopify/hydrogen 2026.4.5 → 2026.10.0-preview.2

package/skills/hydrogen-markets/references/nextjs.md

@@ -0,0 +1,157 @@
+# Next.js App Router
+
+## Contents
+
+- Host-Based Markets
+- Path-Prefix Markets
+- Raw URL Fallback
+
+Next.js App Router Server Components do not receive a standard `Request` object or direct access to the current URL. Use the source that matches the market strategy:
+
+- Host or subdomain markets: read the URL from Hydrogen's request context when the app proxy forwards it.
+- Path-prefix markets: model the market as a route segment, such as `app/[market]/products/[handle]/page.tsx`, and read it from `params`.
+- Raw URL markets: use a request-context handoff in `proxy.ts`; do not invent a second URL header.
+
+---
+
+## Host-Based Markets
+
+Use this for domain or subdomain routing, like `example.ca`, `fr.example.com`, or `ca.example.com`.
+
+`proxy.ts` creates a request context from the `NextRequest`, forwards `requestContext.getForwardedRequestHeaders()`, and Server Components recreate the request context from `headers()`. That handoff includes the original URL.
+
+```ts
+// lib/markets.ts
+type Market = {
+  country: string;
+  language: string;
+  pathPrefix?: string;
+};
+
+const DEFAULT_MARKET = {
+  country: "US",
+  language: "EN",
+} satisfies Market;
+
+const MARKET_BY_HOST = {
+  "example.com": { country: "US", language: "EN" },
+  "example.ca": { country: "CA", language: "EN" },
+  "fr.example.com": { country: "FR", language: "FR" },
+} satisfies Record<string, Market>;
+
+export function getMarketFromHeaders(headers: Pick<Headers, "get">): Market {
+  const forwardedUrl = headers.get("x-storefront-url");
+  if (!forwardedUrl) return DEFAULT_MARKET;
+
+  const { hostname } = new URL(forwardedUrl);
+  const host = hostname.toLowerCase();
+
+  return MARKET_BY_HOST[host] ?? DEFAULT_MARKET;
+}
+```
+
+Use an allowlist like `MARKET_BY_HOST`; do not blindly trust request hosts for anything security-sensitive.
+
+```ts
+// lib/storefront.ts
+import "server-only";
+import {
+  createStorefrontClient,
+  createShopifyRequestContext,
+} from "@shopify/hydrogen";
+import { headers } from "next/headers";
+import { cache } from "react";
+
+import { storefrontConfig } from "./config";
+import { getMarketFromHeaders } from "./markets";
+
+export const getStorefrontClient = cache(async () => {
+  const requestHeaders = await headers();
+  const request = { headers: requestHeaders };
+  const requestContext = createShopifyRequestContext({
+    request,
+    i18n: getMarketFromHeaders(requestHeaders),
+  });
+
+  return createStorefrontClient({
+    type: "public",
+    requestContext,
+    config: {
+      storeDomain: storefrontConfig.storeDomain,
+      publicStorefrontToken: storefrontConfig.publicStorefrontToken,
+    },
+  });
+});
+```
+
+`headers()` is a request-time API, so pages using this helper are dynamically rendered.
+
+---
+
+## Path-Prefix Markets
+
+Use this for routes like `/en-ca/products/shirt` or `/fr-fr/products/shirt`. Model the market prefix as a route segment so Server Components can read it from `params` without `headers()`.
+
+```ts
+// lib/path-markets.ts
+type Market = {
+  country: string;
+  language: string;
+  pathPrefix?: string;
+};
+
+const DEFAULT_MARKET = {
+  country: "US",
+  language: "EN",
+} satisfies Market;
+
+const MARKET_BY_PARAM = {
+  "en-ca": { country: "CA", language: "EN", pathPrefix: "/en-ca" },
+  "fr-fr": { country: "FR", language: "FR", pathPrefix: "/fr-fr" },
+} satisfies Record<string, Market>;
+
+export function getMarketFromParam(marketParam: string): Market {
+  return MARKET_BY_PARAM[marketParam.toLowerCase()] ?? DEFAULT_MARKET;
+}
+```
+
+For static or ISR-cached pages, use a `private_no_buyer_context` client and pass the market from route params. The page can be prerendered when the route uses `generateStaticParams` and does not call request-time APIs like `headers()` or `cookies()`.
+
+```ts
+// lib/static-storefront.ts
+import { createStorefrontClient, createShopifyRequestContext } from "@shopify/hydrogen";
+
+import { getMarketFromParam } from "./path-markets";
+
+export function createStaticStorefrontClient(marketParam: string) {
+  const requestContext = createShopifyRequestContext({
+    request: { headers: new Headers() },
+    i18n: getMarketFromParam(marketParam),
+  });
+
+  return createStorefrontClient({
+    type: "private_no_buyer_context",
+    requestContext,
+    config: {
+      storeDomain: process.env.NEXT_PUBLIC_STORE_DOMAIN!,
+      privateStorefrontToken: process.env.PRIVATE_STOREFRONT_API_TOKEN!,
+    },
+  });
+}
+```
+
+Use the query shape from `SKILL.md`: declare `$country` and `$language`, use `@inContext`, and let the client inject the market variables. Use the private client with trusted buyer context instead when the page needs buyer-specific headers, cookies, or personalized data. That path becomes dynamic because it must read request-time data.
+
+---
+
+## Raw URL Fallback
+
+Use raw URLs only when host headers or route params cannot represent the market, usually with rewrites or catch-all route setups.
+
+Use this proxy handoff:
+
+- In `proxy.ts`, create a request context from the `NextRequest`.
+- Forward `requestContext.getForwardedRequestHeaders()` through `NextResponse.next({ request: { headers } })`.
+- In Server Components, recreate a request-like object with `request: { headers: await headers() }`, resolve the market from the forwarded URL header, then create the client request context with that `i18n`.
+
+`createShopifyRequestContext` already persists the URL through `x-storefront-url`, so do not set a parallel URL header unless the app cannot use the proxy handoff.

package/skills/hydrogen-money/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: hydrogen-money
+description: >
+  Guide for formatting Shopify money values in Hydrogen storefronts. Use when
+  rendering product prices, compare-at prices, cart totals, collection price
+  ranges, Shop Pay prices, or any MoneyV2 amount/currencyCode values.
+---
+
+# Money Formatting
+
+Use Hydrogen's `formatMoney()` for Storefront API `MoneyV2` values. Never build money strings by concatenating currency symbols or computing totals client-side.
+
+```ts
+import { formatMoney, type MoneyV2 } from "@shopify/hydrogen";
+
+// `locale` should come from the resolved market. Default only in
+// single-market storefronts; market-aware stores must pass the active locale.
+export function formatPrice(money: MoneyV2, locale = "en-US"): string {
+  return formatMoney(money, { locale }).toString();
+}
+```
+
+## Rules
+
+- Display server-provided money fields: `variant.price`, `variant.compareAtPrice`, `product.priceRange.minVariantPrice`, `line.cost.totalAmount`, `cart.cost.subtotalAmount`, etc.
+- Do not multiply quantity by unit price in the browser. Cart totals are affected by discounts, duties, tax, rounding, and selling plans.
+- Use the active market locale when the app has markets. Do not hardcode `en-US` in market-aware storefronts.
+- Prefer a small app wrapper such as `formatPrice()` so locale and display options are consistent.
+- Use `withoutTrailingZeros` only for presentation choices, never by editing amount strings manually.
+- For price ranges, pass a readonly array of `MoneyV2` values to `formatMoney([...])`.
+
+## Structured Output
+
+`formatMoney()` returns an object that stringifies to the localized price. Use
+`toString()` or template literals for normal UI. Call `formatMoney()` directly
+or add an object-returning wrapper when the design needs split markup:
+
+- `localizedString` - full display string, same as `toString()`.
+- `amount` - localized numeric portion without currency.
+- `numericAmount` - parsed number; do not use for cart totals or currency math.
+- `currencySymbol`, `currencyNarrowSymbol`, `currencyName` - currency display variants.
+- `parts` - `Intl.NumberFormatPart[]` for custom markup.
+- `withoutTrailingZeros`, `withoutTrailingZerosAndCurrency` - presentation-only variants.
+
+For ranges, `formatMoney([min, max], options)` returns an object that stringifies
+to the localized range and exposes `min`, `max`, and `currencyCode`. Range
+inputs must share one currency.
+
+## Examples
+
+```tsx
+<p>{formatPrice(selectedVariant?.price ?? product.priceRange.minVariantPrice, locale)}</p>
+```
+
+```ts
+const range = formatMoney(
+  [product.priceRange.minVariantPrice, product.priceRange.maxVariantPrice],
+  { locale, withoutTrailingZeros: true },
+).toString();
+```
+
+## Anti-Patterns
+
+- `"$" + amount`
+- `Number(amount).toFixed(2)`
+- `line.quantity * Number(line.merchandise.price.amount)`
+- Showing cart totals at full opacity while a related cart mutation is pending.

package/skills/hydrogen-oxygen/SKILL.md

@@ -0,0 +1,245 @@
+---
+name: hydrogen-oxygen
+description: >
+  Audit and adapt an existing Hydrogen storefront for Shopify Oxygen and local MiniOxygen. Use when asked to make a
+  server-capable Hydrogen project Oxygen-compatible, add or repair its Worker server entrypoint, configure MiniOxygen,
+  remove Node runtime assumptions, wire Worker environment, cache, and waitUntil, or verify dev, preview, and deploy
+  behavior.
+---
+
+# Making A Hydrogen App Oxygen-Compatible
+
+Treat Oxygen as a Web Worker runtime, not a Node server. Preserve the app's routes and storefront behavior while
+adapting its server runtime, build output, and request lifecycle.
+
+Master checklist:
+
+```text
+- [ ] Inspect the framework, server entrypoint, and build target
+- [ ] Read the matching framework reference when available
+- [ ] Produce an Oxygen-compatible module Worker at `<root>/server.ts` or configure its custom path
+- [ ] Produce one server bundle and a public assets directory
+- [ ] Run the Worker locally with MiniOxygen
+- [ ] Thread env, cache, and waitUntil through each request
+- [ ] Create request-dependent Shopify resources per request
+- [ ] Remove Node-only runtime assumptions
+- [ ] Typecheck and build
+- [ ] Exercise dynamic routes in dev and preview
+- [ ] Run Hydrogen smoke tests
+```
+
+## Inspect The App
+
+Run from the app root. Read `package.json`, framework and bundler configuration, server and client entries, SSR setup,
+request middleware, environment declarations, deployment scripts, and the existing production adapter. If there is no
+`package.json`, stop and tell the user to run the skill from the app root.
+
+Identify how the framework:
+
+- turns an incoming Web `Request` into the app's request handler
+- renders SSR responses and hydrates the browser
+- passes request-scoped context to loaders, middleware, or server functions
+- builds and selects its server entrypoint
+- serves static assets alongside dynamic Worker responses
+
+Read [references/react-router.md](references/react-router.md) for a React Router framework-mode app. For another
+framework, apply the generic Oxygen contract below through its Worker adapter and existing conventions. Do not copy
+React Router filenames or APIs into another framework. If no Worker adapter or build target exists, identify that gap
+explicitly before changing application code.
+
+## Preserve App Behavior
+
+Keep existing routes, middleware, cart, customer accounts, analytics, search, redirects, cookies, and response headers
+unless the user explicitly asks to remove them. Reuse the app's context and middleware architecture where possible. Do
+not replace the app with a starter or rewrite framework-owned routing merely to change runtimes.
+
+Keep route-template wiring used by `handleShopifyRedirects`, Shopify scripts, and predictive search. Oxygen compatibility
+does not make those routes optional.
+
+## Implement The Oxygen Worker Contract
+
+Use `<root>/server.ts` as the default Worker entrypoint. Oxygen and MiniOxygen discover that path without extra
+configuration. If the entrypoint lives elsewhere, configure the same project-relative path everywhere it is consumed:
+
+- pass `entry` to MiniOxygen, for example `oxygen({ entry: "./src/worker.ts" })`
+- pass `--entry ./src/worker.ts` to Shopify Hydrogen CLI commands that run or deploy the Worker
+
+Do not rely on a framework's server-file convention to make a custom entrypoint discoverable by Oxygen.
+
+Produce a module Worker whose default export handles requests with the platform values Oxygen provides:
+
+```ts
+export default {
+  async fetch(request: Request, env: Env, executionContext: ExecutionContext) {
+    const waitUntil = executionContext.waitUntil.bind(executionContext);
+    const cache = await caches.open("hydrogen");
+
+    return handleRequest(request, { env, waitUntil, cache });
+  },
+};
+```
+
+Adapt `handleRequest` and the context shape to the framework. The server build must bundle this entry as a Web-compatible
+module Worker and return a standard `Response`. Use Web APIs such as `Request`, `Response`, `Headers`, `URL`, `fetch`,
+Web Crypto, and Web streams throughout runtime code.
+
+Keep server rendering Web-compatible. Use the framework's Worker renderer or Web-stream renderer instead of a Node
+stream renderer. Add or change a browser hydration entry only when the framework requires it; see the matching reference
+for exact entry files.
+
+## Configure MiniOxygen And Deployment
+
+Use MiniOxygen to run the same Worker contract locally. For a Vite app:
+
+- preserve an existing compatible `@shopify/mini-oxygen` version; otherwise install the latest available version
+- add `@shopify/oxygen-workers-types`
+- add `oxygen()` from `@shopify/mini-oxygen/vite` to the Vite plugins
+- make both development and built preview modes execute the Worker entrypoint
+
+Require MiniOxygen 4.2.0 or newer for the behavior described here. Do not replace a compatible existing version merely
+to change its version range.
+
+Use plain `oxygen()` when the app uses `<root>/server.ts` and does not need explicit binding configuration; MiniOxygen
+uses Vite's environment loading when no `env` option is provided. Values can come from the active mode's `.env` files
+and from variables already exported into `process.env`; Vite merges both sources. Worker runtime code receives the
+result through its `env` argument rather than reading `process.env`. Otherwise pass the custom `entry` or bindings
+explicitly. For a non-Vite build, use the framework's Worker adapter or MiniOxygen integration instead of introducing
+Vite only to copy another framework's setup.
+
+Add `@shopify/cli` and a `shopify hydrogen deploy` script when the project does not already have a supported Oxygen
+deployment path. Use the latest available `@shopify/cli`. Preserve the installed `@shopify/hydrogen` version unless the
+user separately asks to upgrade it.
+
+## Produce Deployable Build Output
+
+Build two deployable outputs:
+
+- one bundled Worker server module
+- one directory containing public client assets
+
+Configure the server build to avoid code splitting. Oxygen expects a single executable Worker bundle rather than a
+server entry that depends on additional server chunks.
+
+### Default Vite Layout
+
+For the common Vite setup with `<root>/server.ts`, let the Oxygen plugin detect output locations from Vite
+configuration. `vite preview` and `shopify hydrogen deploy` generally need no `previewEntry`, `--assets-dir`, or
+`--worker-dir` overrides. When Vite does not expose custom locations, Oxygen prefers this fallback layout:
+
+```text
+dist/
+├── client/
+└── server/
+    └── index.js
+```
+
+The Worker file may use `.js` or `.mjs`. A build may also emit `oxygen.json` beside the Worker as a compatibility-date
+artifact; preserve and deploy it with the server output.
+
+### Custom Or Non-Default Layout
+
+Only add explicit output configuration when the framework emits a layout that Oxygen or MiniOxygen does not discover:
+
+- pass the built Worker file to MiniOxygen as `previewEntry` so `vite preview` executes it
+- pass the asset directory to deployment with `--assets-dir <path>`
+- pass the Worker directory to deployment with `--worker-dir <path>`
+
+For example:
+
+```ts
+oxygen({
+  entry: "./src/worker.ts",
+  previewEntry: "./build/server/index.mjs",
+});
+```
+
+```sh
+shopify hydrogen deploy --assets-dir ./build/client --worker-dir ./build/server
+```
+
+Treat `entry` and `previewEntry` as different stages: `entry` points to the source Worker used during development;
+`previewEntry` points to the built Worker module. The directory passed to `--worker-dir` must contain `index.js` or
+`index.mjs` at its root. Pass directories, not individual files, to `--assets-dir` and `--worker-dir`.
+
+## Keep Request State Request-Scoped
+
+Pass the incoming `env`, bound `waitUntil`, and an Oxygen cache through the framework's request context. Pass `cache`
+and `waitUntil` together in the Hydrogen client config:
+
+```ts
+createStorefrontClient({
+  // Existing client options...
+  config: {
+    // Existing config options...
+    cache,
+    waitUntil,
+  },
+});
+```
+
+The `Cache` returned by `caches.open("hydrogen")` is accepted directly by Hydrogen clients. Remove custom cache
+adapters and process-local cache dependencies such as `lru-cache`; do not wrap the Workers cache in an adapter.
+`waitUntil` lets background cache revalidation continue after the response has been returned, so pass the bound
+function whenever the platform provides it.
+
+Create values that depend on the request, environment, headers, locale, session, or response headers inside the request
+lifecycle, including:
+
+- `createShopifyRequestContext(...)`
+- `createStorefrontClient(...)`
+- `createCustomerAccountClient(...)`
+- cart and customer session managers
+- request-specific response header collections
+
+Keep only pure constants and stateless factories at module scope. Use `caches.open("hydrogen")` instead of a process-local
+LRU cache for Hydrogen request caching, and use `executionContext.waitUntil` for background cache work.
+
+## Configure Environment And Types
+
+Declare the Worker's actual `Env` bindings and include `@shopify/oxygen-workers-types` in app runtime types. Keep
+`.env.example` committed with placeholders and `.env` ignored. Let Oxygen provide deployed secrets as environment
+bindings and MiniOxygen provide local bindings.
+
+Read server secrets from the request's `env`, never from `process.env` or browser-importable modules. Keep public browser
+configuration separate from private Worker bindings. Start from the existing TypeScript config rather than replacing it;
+retain Node types where build tooling genuinely needs them. Node and Worker types can usually coexist when one TypeScript
+program includes both Worker runtime code and Vite or build files. If their globals conflict, use separate runtime and
+build-tool tsconfigs instead of masking the conflict with `skipLibCheck`.
+
+## Remove Incompatible Runtime Assumptions
+
+Inspect server runtime code for:
+
+- `process`, `Buffer`, `node:*`, filesystem, and Node crypto APIs
+- Node streams and Node-specific SSR renderers
+- framework Node server adapters and start commands
+- CommonJS globals or dependencies that require `module` or `require` at runtime
+- in-memory caches used in place of the Workers Cache API
+- classic Hydrogen runtime or Vite integrations
+
+Replace each runtime dependency with a Web API or the framework's Worker adapter. Do not mechanically remove packages
+used only by build configuration, tests, or transitive dependencies.
+
+## Verify The Result
+
+Run the applicable formatter, lint, typecheck, GraphQL validation, tests, and production build. Run both development and
+built preview modes under MiniOxygen, then request routes that exercise server rendering and Hydrogen data rather than
+only static assets.
+
+At minimum, check `/`, one product, one collection, `/search`, `/cart`, and `/account` when those routes exist. Confirm
+environment bindings load, dynamic responses come from the Worker, mutations preserve cookies and headers, cache work
+uses `waitUntil`, and no Node or CommonJS runtime error appears. A server starting is not sufficient evidence that the
+Worker request path works.
+
+Use the local `hydrogen-smoke-test` skill for broader Hydrogen request-handler, cart, analytics, markets, and production
+checks. Exercise mutations through the real cart UI or the framework's cart action rather than hand-crafting an internal
+Hydrogen payload; follow that skill for the concrete cookie and header checks. Fix failures and rerun the affected checks.
+Report every validation step that could not be completed and why.
+
+## Stop Conditions
+
+- No `package.json` exists at the current app root.
+- The app is static-only and has no server request lifecycle to deploy.
+- The framework cannot produce a module Worker and no suitable adapter or server-build hook is available.
+- Required production secrets are unavailable for live route verification; complete static/build verification and
+  report runtime checks as blocked instead of inventing values.