@shopify/hydrogen 2026.4.5 → 2026.10.0-preview.2

package/skills/hydrogen-setup/steps/1-inspect-app.md

@@ -0,0 +1,62 @@
+# 1. Inspect App
+
+## Basic Compatibility
+
+Read `package.json` in the current directory.
+
+If it does not exist, stop and tell the user this skill must run in a javascript application with a `package.json` at its root.
+
+If it does not contain `@shopify/hydrogen@preview` (or a more specific hash) in its dependencies, ask the user to install it. Do not assume package managers or install for the user.
+
+### Continue when
+
+- [ ] Current directrory has `package.json`
+- [ ] Current project includes `@shopify/hydrogen@preview` or similar in its dependencies
+
+## Styling
+
+Identify how the app handles styling. You must follow an already established design system or library if present. Do not introduce a new styling approach when one already exists.
+
+Common fingerprints:
+
+| Library | Look for |
+| --- | --- |
+| Tailwind CSS | `tailwind.config.*` at root; `@tailwindcss/vite` / `@tailwindcss/postcss` / `tailwindcss` in dependencies; `@import "tailwindcss"` or `@tailwind` directives in CSS; utility-heavy `className` / `class` usage |
+| StyleX | `@stylexjs/stylex` in dependencies; `stylex.config.*` or StyleX Babel/SWC plugin config; `stylex.create(...)` / `stylex.props(...)` in components |
+| CSS Modules | `*.module.css` / `*.module.scss` co-located with components; `import styles from '...module.css'` |
+| Sass / SCSS | `sass` / `sass-embedded` in dependencies; `*.scss` / `*.sass` stylesheets |
+| Panda CSS | `@pandacss/dev` / styled-system output; `panda.config.*` at root |
+| UnoCSS | `unocss` in dependencies; `uno.config.*` / `unocss.config.*` at root |
+| styled-components | `styled-components` in dependencies; `styled.*` / `createGlobalStyle` usage |
+| Plain CSS | Global `*.css` imports with no module/utility/runtime styling library detected |
+
+If multiple signals appear, prefer the one the app already uses for layout and components (config + component usage), not a transitive dependency alone. If none of the above match, treat the app as plain CSS / unstyled and keep new UI minimal semantic HTML.
+
+### Continue when
+
+- [ ] Styling approach identified (or confirmed absent)
+
+
+## Framework specific references
+
+Every skill prefixed with `hydrogen-` *may* ship a framework-specific instruction file under its own `references/`. After detecting the framework, check that skill's `references/` for the matching file and read it before making framework-specific choices. If no matching reference exists, continue from the generic instructions and follow the app's existing conventions.
+
+Inspect dependencies, configuration files, server entry points, route directories, and existing request lifecycle code. Identify whether the app has a framework that can run server code and expose request handlers, middleware, loaders, server functions, or route handlers.
+
+Common root-level fingerprints:
+
+| Framework | Look for | Reference file to look for |
+| --- | --- | --- |
+| Astro | `astro.config.ts` / `astro.config.mjs` at root | `astro.md` |
+| Next.js | `next.config.ts` / `next.config.js` / `next.config.mjs` at root | `nextjs.md` |
+| React Router | `react-router.config.ts` at root | `react-router.md` |
+| Nuxt | `nuxt.config.ts` / `nuxt.config.js` at root | `nuxt.md` |
+| SvelteKit | `svelte.config.js` / `svelte.config.ts` at root | `sveltekit.md` |
+| SolidStart | `app.config.ts` at root with `@solidjs/start` | `solidstart.md` |
+| Marko | `marko.config.js` / `marko.config.ts` at root, or `@marko/run` | `marko.md` |
+
+Do not hard block just because no reference file exists. Continue when the app has a real server request lifecycle where Hydrogen can run before routing and handle 404 redirects after routing. Stop only when the app is clearly browser-only, static-only, or has no way to run server code.
+
+### Continue when
+
+- [ ] Able to determine that the application serves HTTP requests

package/skills/hydrogen-setup/steps/10-analytics.md

@@ -0,0 +1,10 @@
+# Analytics
+
+Invoke the `hydrogen-analytics` skill to wire storefront analytics. This depends on the request handlers (scaffold step) and Shopify runtime scripts being in place. Read `../references/analytics.md` for the full consent and setup details when needed.
+
+## Continue when
+
+- [ ] Page view analytics events publish on route navigation, including client-side navigations
+- [ ] Product, collection, search, and cart view events publish on their routes
+- [ ] Cart update tracking publishes deltas when line items change
+- [ ] Analytics events respect consent: no destination receives events before consent is granted where consent is required

package/skills/hydrogen-setup/steps/11-verify.md

@@ -0,0 +1,31 @@
+# Final Verification
+
+Run this step only after every previous step's criteria pass. If any command fails, fix the app and rerun the failed command before moving on.
+
+This step is mandatory and executable: every command below must actually run in this session, and its output must show it passed. Do not mark a check passed from memory, from an earlier run before subsequent code changes, or from reading the code. Do not report the setup as complete while any command is failing or unrun — a summary written before verification is a failed setup.
+
+## Run The App's Own Checks
+
+Inspect `package.json` scripts and run the applicable commands in this order:
+
+1. Formatting fixer when present: `format`.
+2. Static checks when present: `lint`, `typecheck`, or `check`. These must include `hydrogen gql check` — the `hydrogen-storefront-client` and `hydrogen-customer-account` skills chain it into `typecheck`; verify the chain is still in place before trusting a green run.
+3. Build when present: `build`.
+4. Tests when present: `test`.
+5. Formatting check when present and distinct from `format`: `format:check`.
+
+If Playwright is present, run it headless.
+
+### Continue when
+
+- [ ] Every applicable script was executed in this session, after the last code change, and passed
+- [ ] `hydrogen gql check` ran as part of static checks (not skipped)
+
+## Run Runtime Smoke Tests
+
+Invoke the `hydrogen-smoke-test` skill for runtime verification of request handlers, navigation links, cart, product, collection/search, account, analytics, markets, money, and production-mode behavior. Run the request-handler curl checks against both dev and production builds when the framework supports both.
+
+### Continue when
+
+- [ ] Smoke checks pass against the dev server
+- [ ] Smoke checks pass against the production build when the framework supports running one locally

package/skills/hydrogen-setup/steps/2-scaffold.md

@@ -0,0 +1,86 @@
+# Scaffold
+
+## Use Storefront Route Conventions
+
+Preserve the app's existing route shape when present. When there is no established convention, use the standard paths:
+
+- `/collections` for collection listing.
+- `/collections/{handle}` for collection detail.
+- `/search` for search results.
+- `/products/{handle}` for product detail. Use plural `products`, not `/product`.
+- `/cart` for the full cart page.
+
+Hydrogen-owned handlers are not page routes: `/api/cart`, `/api/{api-version}/graphql.json`, 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 redirects, `/admin` redirects, and Storefront URL redirects belong in the `hydrogen-request-handlers` wiring.
+
+Invoke the `hydrogen-routing` skill and create the shared route template manifest for Shopify resources such as products, collections, pages, blogs, or articles.
+
+### Continue when
+
+- [ ] Route templates are set up
+
+## Use Standard Environment Names
+
+Use these canonical environment variable names throughout the app (kept in sync with `hydrogen-storefront-client`):
+
+- `PUBLIC_STORE_DOMAIN` for the Shopify store domain.
+- `PUBLIC_STOREFRONT_API_TOKEN` for the public Storefront API token.
+- `PRIVATE_STOREFRONT_API_TOKEN` for the private Storefront API token.
+- `PUBLIC_STOREFRONT_ID` for analytics `storefrontId`; use `"0"` when the app does not have a storefront ID.
+- `PUBLIC_CHECKOUT_DOMAIN` for app-level checkout-domain configuration such as CSP setup. Checkout links should come from cart data, usually `cart.checkoutUrl`.
+- `SHOP_ID` for the numeric Shopify shop ID string. Required by Shopify runtime scripts (`ShopifyScripts`) for every storefront, and by Customer Account API.
+- `PUBLIC_CUSTOMER_ACCOUNT_API_CLIENT_ID` for Customer Account OAuth.
+- `CUSTOMER_ACCOUNT_SESSION_SECRET` for encrypted cookie examples. Prefer opaque server-side sessions in production apps.
+
+If the framework requires a prefix to expose client-side variables, preserve the canonical suffix and add only the required framework prefix. Never expose `PRIVATE_STOREFRONT_API_TOKEN` to the client.
+
+List `PUBLIC_STOREFRONT_API_TOKEN` in the app's env example file as a commented-out entry (`# PUBLIC_STOREFRONT_API_TOKEN=`). The Storefront client accepts `undefined` as tokenless access, which is all mock.shop supports, so the scaffold works before the user has tokens and upgrades in place when they add one. Do not write an uncommented empty assignment (`PUBLIC_STOREFRONT_API_TOKEN=`): env loaders parse that as an empty string, and the client rejects empty tokens. Recommend filling it in (or switching to a private client) once the app targets a real store.
+
+### Continue when
+
+- [ ] Env vars follow the canonical names (plus any required framework prefix)
+- [ ] `PUBLIC_STOREFRONT_API_TOKEN` is listed commented-out in the env example until the user provides a token
+- [ ] `PRIVATE_STOREFRONT_API_TOKEN` is not exposed to the client
+
+## Keep Environment Access Server-Side
+
+Never read `process.env`, `import.meta.env`, or framework environment modules from client components, browser singletons, or modules imported by client components. Environment access belongs in server-only modules, route loaders, route handlers, middleware, server functions, or the framework's server environment API.
+
+Prefer resolving and formatting values on the server and passing them to client UI as serialized data. Any object or property derived from env or server config — such as the `shop` object passed to `ShopifyScripts` — should be assembled in the framework's server boundary (RSC, route loaders, server functions, worker request handlers) and flow down as props or loader data, never assembled in client code.
+
+Client code should use same-origin Hydrogen endpoints/handlers for Shopify work. Private tokens and server-only config must never cross the server boundary.
+
+### Continue when
+
+- [ ] No client component or browser-imported module reads `process.env`, `import.meta.env`, or framework env modules
+- [ ] Values derived from env are resolved in server boundaries and reach client UI only as serialized props or loader data
+
+## Set Up The Storefront API Client
+
+Invoke the `hydrogen-storefront-client` skill to wire the Storefront API client or client factory for the detected framework.
+
+### Continue when
+
+- [ ] Storefront client is initialised with a shopify request context
+- [ ] A test graphql query can be ran on the home page and returns the correct type
+- [ ] `hydrogen gql check` is chained into the `typecheck` script (per the `hydrogen-storefront-client` skill) and passes
+
+
+## Install API Route Handlers
+
+Invoke the `hydrogen-request-handlers` skill to wire `handleShopifyRoutes` before routing, `handleShopifyRedirects` after a 404 or in the framework's catch-all route, and request-context response-header propagation for custom and framework responses.
+
+### Continue when
+
+- [ ] `/api/graphiql` returns 200 in development mode
+- [ ] `/admin` redirects to the Shopify Admin in development mode
+
+## Set Up The Customer Account API
+
+Invoke the `hydrogen-customer-account` skill to create the `customerSession` module and register the account route handlers through the `handleShopifyRoutes` setup from the previous section.
+
+### Continue when
+
+- [ ] `customerSession` is created at module scope
+- [ ] customer account handlers (result of calling `createCustomerAccountServerHandlers`) is registered through `handleShopifyRoutes`
+- [ ] `/account/login` does not 404
+- [ ] `hydrogen gql check` passes when any page renders Customer Account API data

package/skills/hydrogen-setup/steps/3-build-home-page.md

@@ -0,0 +1,37 @@
+# Build home page
+
+Create a simple server-rendered home page that proves Hydrogen is wired correctly.
+
+## Data Requirements
+
+Use the shared Storefront API client to fetch both collections and products in the page's server data-loading boundary.
+
+The home query should include:
+
+- Collection `id`, `title`, `handle`, and optional `image { url altText }`.
+- Product `id`, `title`, `handle`, optional `featuredImage { url altText }`, and `priceRange { minVariantPrice { amount currencyCode } }`.
+
+Do not fetch cart data for the home page. Cart belongs to the cart route and navbar link state, not to the home page sample.
+
+## Rendering Requirements
+
+- Render collections and products as separate sections.
+- Link collection cards using the app's routing template (`hydrogen-routing` skill).
+- Link product cards using the app's existing product route templates (`hydrogen-routing` skill).
+- Format money with the local `hydrogen-money` skill; never do client-side currency arithmetic.
+- Use empty states when collections or products are missing.
+- Keep styles local to the app's existing styling approach. If there is no styling system, use minimal semantic HTML.
+
+## Framework Notes
+
+- Next.js App Router: fetch in `app/page.tsx` or a server helper it imports.
+- React Router framework mode: fetch in the index route `loader` and render from loader data.
+- SvelteKit: fetch in `+page.server.ts` and render in `+page.svelte`.
+- Astro: fetch in `src/pages/index.astro` frontmatter.
+- SolidStart: fetch through a server query or route data API used by `src/routes/index.tsx`.
+
+## Continue when
+
+- [ ] The home page renders products and collections
+- [ ] Product and collection links point to the app's actual route shape
+- [ ] Prices display with digits and units (e.g.: $20.95)

package/skills/hydrogen-setup/steps/4-collection-and-search.md

@@ -0,0 +1,14 @@
+# Build Collection And Search Browsing
+
+Invoke the `hydrogen-collection-browser` skill when adding collection routes, search routes, filter sidebars, sort controls, active filter chips, or URL-synced product grids.
+
+## Continue when
+
+- [ ] Filtering and sorting update the URL without scroll reset when hydrated.
+- [ ] Checkbox filters and price min/max controls both render, apply, and persist after reloading the URL.
+- [ ] Reloading the filtered URL server-renders the same filtered state.
+- [ ] With JavaScript disabled, checking filters and submitting the form loads the filtered URL.
+- [ ] With JavaScript disabled, the load-more / pagination link loads the next page server-side.
+- [ ] Active filter chips remove only one filter and preserve unrelated params.
+- [ ] Searching with a search term does not erase the search term (preserves `q` search param).
+- [ ] Back/forward navigation settles loading state.

package/skills/hydrogen-setup/steps/5-cart.md

@@ -0,0 +1,10 @@
+# Cart
+
+## Add The Cart Route
+
+Use the local `hydrogen-cart-ui` skill to create the cart route at the framework's idiomatic `/cart` path.
+
+### Continue when
+
+- [ ] The `/cart` route (or its custom route template) loads the cart and shows the empty state UI
+- [ ] With javascript disabled, the `/cart` route still shows the empty state UI (progressive enhancement)

package/skills/hydrogen-setup/steps/6-product-detail-page.md

@@ -0,0 +1,416 @@
+# Product Detail Page
+
+Create a server-rendered product detail route with a variant picker and image.
+
+## Route And Data
+
+- Use the app's existing product route convention when present; otherwise create `/products/{handle}`.
+- Fetch the product by handle in the framework's server data-loading boundary.
+- Derive URL-selected options with `getSelectedProductOptions` and pass them as `$selectedOptions` to the product query.
+- Start from the sample query below. Extend it for UI needs (extra media, SEO fields, related products). Keep one reusable `VariantFields` fragment shared by `firstSelectableVariant`, `selectedOrFirstAvailableVariant`, and `adjacentVariants` so `selectedVariant` always has the fields the UI needs after option selection.
+- After writing or changing the product query, run the `hydrogen-storefront-client` skill's headless query validation check. Do not rely on TypeScript alone to catch invalid Storefront API fields.
+- Check GraphQL `errors` before checking `data.product`. If the query returns errors, log them in the server console and return a 500 response. Return a 404 only when the query has no GraphQL errors and `data.product` is missing.
+
+### `getSelectedProductOptions`
+
+Treat each search param as an option name/value pair (`?Color=Red&Size=M` → `[{name:"Color",value:"Red"},{name:"Size",value:"M"}]`). Pass the result into the Storefront API query.
+
+```ts
+import { getSelectedProductOptions } from "@shopify/hydrogen";
+
+const selectedOptions = getSelectedProductOptions({
+  searchParams: new URL(request.url).searchParams,
+});
+
+// Optional: ignore non-option params (utm, ref, etc.) once option names are known
+const selectedOptions = getSelectedProductOptions({
+  searchParams,
+  allowedOptionNames: product.options.map((option) => option.name),
+});
+```
+
+Passing `allowedOptionNames: []` filters out every option.
+
+The `variant` search param is reserved for Liquid-style numeric variant ids and is never treated as an option name. Pass `routeTemplates` to `handleShopifyRoutes` (see the local `hydrogen-request-handlers` skill) so `?variant=<id>` product links redirect to the canonical option-params URL before this loader runs.
+
+### Minimum product query
+
+Extend and adjust fields as the UI needs them.
+
+```ts
+import { gql, type StorefrontApi } from "@shopify/hydrogen";
+
+export const VARIANT_FIELDS_FRAGMENT = gql(`
+  fragment VariantFields on ProductVariant {
+    id
+    title
+    availableForSale
+    selectedOptions {
+      name
+      value
+    }
+    price {
+      amount
+      currencyCode
+    }
+    compareAtPrice {
+      amount
+      currencyCode
+    }
+    image {
+      url
+      altText
+      width
+      height
+    }
+    product {
+      title
+      handle
+    }
+    sku
+  }
+`);
+
+export const PRODUCT_QUERY = gql(
+  `
+  query Product(
+    $handle: String!
+    $selectedOptions: [SelectedOptionInput!]!
+    $country: CountryCode
+    $language: LanguageCode
+  ) @inContext(country: $country, language: $language) {
+    product(handle: $handle) {
+      id
+      handle
+      title
+      vendor
+      description
+      descriptionHtml
+      requiresSellingPlan
+      options {
+        name
+        optionValues {
+          name
+          firstSelectableVariant {
+            ...VariantFields
+          }
+          swatch {
+            color
+            image {
+              ... on MediaImage {
+                image {
+                  url
+                  altText
+                }
+              }
+            }
+          }
+        }
+      }
+      encodedVariantExistence
+      encodedVariantAvailability
+      selectedOrFirstAvailableVariant(
+        selectedOptions: $selectedOptions
+        ignoreUnknownOptions: true
+        caseInsensitiveMatch: true
+      ) {
+        ...VariantFields
+      }
+      adjacentVariants(
+        selectedOptions: $selectedOptions
+        ignoreUnknownOptions: true
+        caseInsensitiveMatch: true
+      ) {
+        ...VariantFields
+      }
+      media(first: 8) {
+        nodes {
+          __typename
+          id
+          mediaContentType
+          alt
+          ... on MediaImage {
+            image {
+              url
+              altText
+              width
+              height
+            }
+          }
+          previewImage {
+            url
+            altText
+            width
+            height
+          }
+        }
+      }
+      priceRange {
+        minVariantPrice {
+          amount
+          currencyCode
+        }
+        maxVariantPrice {
+          amount
+          currencyCode
+        }
+      }
+    }
+  }
+`,
+  [VARIANT_FIELDS_FRAGMENT],
+);
+
+export type ProductData = NonNullable<StorefrontApi.ResultOf<typeof PRODUCT_QUERY>["product"]>;
+```
+
+### Example data fetching
+
+```ts
+const selectedOptions = getSelectedProductOptions({
+  searchParams: new URL(request.url).searchParams,
+});
+
+const { data, errors } = await storefrontClient.graphql(PRODUCT_QUERY, {
+  variables: { handle, selectedOptions },
+});
+
+if (errors) {
+  console.error("[hydrogen] Product query failed", errors);
+  throw new Response("Product query failed", { status: 500 });
+}
+
+if (!data?.product) {
+  throw new Response("Product not found", { status: 404 });
+}
+```
+
+## UI
+
+- You must invoke the `hydrogen-variant-form` skill for option controls, add-to-cart form structure, URL selection, combined listings, price display, disabled states, sold-out states, cart error display, and user acceptance tests. Do not duplicate its rules or invent separate variant matrix logic.
+- When the cart drawer is configured with the canonical anchor trigger, follow the `hydrogen-cart-drawer` skill's guidance and open optimistic state via `formProps({ beforeSubmit: openCartDrawer })`; the samples below use `beforeSubmit`.
+- Product route loaders and server helpers may read env indirectly through server-only client/config modules. Product client components must not read `process.env`, `import.meta.env`, or framework env modules.
+
+### React
+
+Create typed bindings once from `@shopify/hydrogen/react`:
+
+```ts
+// lib/product.ts
+import { createProductComponents } from "@shopify/hydrogen/react";
+import type { ProductData } from "./product-query";
+
+export const { ProductProvider, useProduct, useProductForm } =
+  createProductComponents<ProductData>();
+```
+
+Wrap the purchase UI in `ProductProvider`. Put same-product URL navigation in `onSelect`, not inside each option control:
+
+```tsx
+import { ProductProvider, useProductForm } from "~/lib/product";
+
+export function ProductDetails({ product }: { product: ProductData }) {
+  const navigate = useNavigate(); // or Next.js router.replace
+
+  return (
+    <ProductProvider
+      product={product}
+      onSelect={(result) => {
+        const targetHandle =
+          result.selectedVariant?.product?.handle ?? product.handle;
+        void navigate(variantUrl(targetHandle, result.selectedOptions), {
+          replace: true,
+          preventScrollReset: true,
+        });
+      }}
+    >
+      <ProductPurchasePanel product={product} />
+    </ProductProvider>
+  );
+}
+```
+
+`useProduct` is for read-only selection state (price, gallery, analytics). `useProductForm` adds form bindings (`register`, `formProps`, `pending`):
+
+```tsx
+function ProductPrice({ product }: { product: ProductData }) {
+  const { selectedVariant } = useProduct();
+  const price = selectedVariant?.price ?? product.priceRange.minVariantPrice;
+  return <p>{formatPrice(price)}</p>;
+}
+
+function ProductPurchasePanel({ product }: { product: ProductData }) {
+  const { options, selectedVariant, formProps, register, errors } =
+    useProductForm();
+  const addable = canAddToCart(product, options);
+
+  return (
+    <>
+      {/* Option controls: see hydrogen-variant-form + its React reference */}
+      <form {...formProps({ beforeSubmit: openCartDrawer })}>
+        <input type="hidden" {...register("merchandiseId", {})} />
+        <input {...register("quantity", { defaultValue: 1 })} />
+        <button {...register("addToCart", {})} disabled={!addable}>
+          {addable
+            ? "Add to cart"
+            : selectedVariant
+              ? "Sold out"
+              : "Select options"}
+        </button>
+      </form>
+      {errors.userErrors.length > 0 ? (
+        <ul role="alert">
+          {errors.userErrors.map((error, index) => (
+            <li key={index}>{error.message}</li>
+          ))}
+        </ul>
+      ) : null}
+    </>
+  );
+}
+```
+
+Framework notes:
+
+- Next.js App Router: fetch in the server page; put `ProductProvider` and the form in a `"use client"` component. Use `router.replace(url, { scroll: false })` in `onSelect`.
+- React Router: put URL sync in provider `onSelect`. Same-product option values are GET `<Link>`s that spread `register("optionValue", ...)` (no-JS fallback). Cross-product values use `<Link preventScrollReset>`. See the `hydrogen-variant-form` React reference.
+
+### Vue
+
+Create typed bindings once from `@shopify/hydrogen/vue`:
+
+```ts
+// storefront/product.ts
+import { createProductComponents } from "@shopify/hydrogen/vue";
+import type { ProductData } from "./product-types";
+
+export const { ProductProvider, useProduct, useProductForm } =
+  createProductComponents<ProductData>();
+```
+
+Wrap the page (or purchase panel) in `ProductProvider`. Sync the URL from `onSelect`:
+
+```vue
+<script setup lang="ts">
+import { buildProductSelectionSearchParams } from "@shopify/hydrogen";
+import { ProductProvider, type ProductData } from "~/storefront/product";
+
+const props = defineProps<{ product: ProductData }>();
+const router = useRouter();
+const route = useRoute();
+
+function handleSelect(result: {
+  selectedOptions: { name: string; value: string }[];
+  selectedVariant: { product?: { handle: string } | null } | null;
+}) {
+  const targetHandle =
+    result.selectedVariant?.product?.handle ?? props.product.handle;
+  const params = buildProductSelectionSearchParams({
+    selectedOptions: result.selectedOptions,
+    optionNames: props.product.options.map((option) => option.name),
+    base: queryToSearchParams(route.query),
+  });
+  const query = searchParamsToQuery(params);
+  router.replace({ path: `/products/${targetHandle}`, query });
+}
+
+function queryToSearchParams(query: typeof route.query) {
+  const params = new URLSearchParams();
+  for (const [key, value] of Object.entries(query)) {
+    const values = Array.isArray(value) ? value : [value];
+    for (const item of values) {
+      params.append(key, item ?? "");
+    }
+  }
+  return params;
+}
+
+function searchParamsToQuery(params: URLSearchParams) {
+  const query: Record<string, string | string[]> = Object.create(null);
+  for (const [key, value] of params) {
+    const current = query[key];
+    if (current === undefined) query[key] = value;
+    else if (Array.isArray(current)) current.push(value);
+    else query[key] = [current, value];
+  }
+  return query;
+}
+</script>
+
+<template>
+  <ProductProvider :product="product" :on-select="handleSelect">
+    <ProductPurchasePanel :product="product" />
+  </ProductProvider>
+</template>
+```
+
+`useProduct` for read-only state; `useProductForm` for form bindings. Do not destructure the Vue composable return values — keep the object so getters stay reactive:
+
+```vue
+<script setup lang="ts">
+import { canAddToCart } from "@shopify/hydrogen";
+import {
+  useProduct,
+  useProductForm,
+  type ProductData,
+} from "~/storefront/product";
+import { openCartDrawer } from "~/storefront/cart-drawer";
+
+const props = defineProps<{ product: ProductData }>();
+
+const productState = useProduct();
+const form = useProductForm();
+const addable = computed(() => canAddToCart(props.product, form.options));
+</script>
+
+<template>
+  <p>
+    {{
+      formatMoney(
+        productState.selectedVariant?.price ??
+          product.priceRange.minVariantPrice,
+      )
+    }}
+  </p>
+
+  <!-- Option controls: see hydrogen-variant-form + its Nuxt/Vue reference -->
+
+  <form v-bind="form.formProps({ beforeSubmit: openCartDrawer })">
+    <input type="hidden" v-bind="form.register('merchandiseId', {})" />
+    <input v-bind="form.register('quantity', { defaultValue: 1 })" />
+    <button
+      v-bind="form.register('addToCart', {})"
+      :disabled="!addable || form.pending.value"
+    >
+      {{
+        addable
+          ? "Add to cart"
+          : form.selectedVariant
+            ? "Sold out"
+            : "Select options"
+      }}
+    </button>
+  </form>
+</template>
+```
+
+Same-product option values should be `NuxtLink` (or the app's link component) GET links that `v-bind` `form.register('optionValue', ...)`. Cross-product combined-listing values navigate to the other product. See the `hydrogen-variant-form` Nuxt reference.
+
+### Other Framework Gotchas
+
+- SvelteKit: if using the core store directly, create it once, hydrate on product identity changes, and destroy it on unmount.
+- Astro: only build this route when the app has server output or a server adapter. Put the interactive product form in a hydrated island or client script that owns the store lifecycle.
+- SolidStart: manage the core store lifecycle inside the client component unless a local binding already exists.
+
+## Continue when
+
+- [ ] Directly loading `/products/{handle}` renders product data and a selected or first available variant when one exists
+- [ ] Option values render as interactive elements (links/buttons)
+- [ ] Clicking an option value in the browser changes the selected variant and the URL
+- [ ] Adding a product to cart opens the cart drawer and shows the product in the cart
+- [ ] An invalid or failing product query (e.g.: invalid field) logs the GraphQL error server-side and returns 500, not 404
+- [ ] A valid query for a missing product returns 404
+- [ ] Selecting a variant and refreshing the page persists the same variant selected
+- [ ] With javascript disabled, clicking on a variant option navigates to the selected variant
+- [ ] Cross-product option values use the framework's client-side link component when the app has one.
+- [ ] The product variants form passes the `hydrogen-variant-form` skill's user acceptance tests.