Three changes needed to run against a real storefront rather than mock.shop.
Storefront API version 2025-07 -> 2026-07. Verified before switching: the
API validates the version segment (a bogus one returns NOT_FOUND), and the
fields this app selects all still resolve at 2026-07 — including the two
deprecated ones, ProductOption.values and CartCost.totalTaxAmount, and the
classic customer account mutations.
BREAKING (config): NEXT_PUBLIC_SHOPIFY_STOREFRONT_ACCESS_TOKEN is now
NEXT_PUBLIC_SHOPIFY_PUBLIC_ACCESS_TOKEN. Deploy environments must set the
new name *before* the next build — NEXT_PUBLIC_* values are inlined at
build time, so a stale name silently degrades to a tokenless client and
real-store queries start failing.
Works around a bug in this preview build of @shopify/hydrogen: the client
tags every request with X-Hydrogen-Version, which the Storefront API does
not list in its CORS access-control-allow-headers. Browsers reject the
preflight, fetch throws, and hydrogen reports the generic "SFAPI request
failed". Confirmed by isolating the single header in the browser against a
real store: without it the request reaches the server (401 on a dummy
token), with it fetch throws TypeError: Failed to fetch. This never showed
up on mock.shop, which answers access-control-allow-headers: *.
The header is stripped in the browser only, inside the fetch wrapper the
client already owns; server-side requests are not subject to CORS and keep
sending it. Remove once the API allows the header, or once these queries
move server-side — which is the better fix, and what hydrogen's own
guidance recommends for browser UI.
Verified against a real store: product grid, search (519 results),
product detail with variants, and cartCreate all succeed.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01JaxgqPbFxLsSuLPZom2kdC
Completes the migration started in f8c3ef9. That commit put hydrogen
underneath the existing shopifyFetch wrapper; this one removes the
wrapper so every query uses the package's own client API.
- All 22 call sites now call storefront.graphql(DOCUMENT, { variables })
(cachedStorefront for shop policies) instead of shopifyFetch, which
emulated the old client's {query, variables} -> {data} shape.
- shopifyFetch is replaced by unwrapStorefrontResult(result, operation),
which is only an error policy, not a transport wrapper: it returns
data and throws when Shopify reports GraphQL errors, since hydrogen
returns those rather than throwing. Naming the operation means a
failure points at the call site instead of just at "Shopify".
- Environment reads move to services/shopify/config, so client.ts is
only the hydrogen clients and shop-pay-button no longer imports from
a query module just to get the store domain.
- Removes @shopify/storefront-api-client, the superseded client. It had
no importers.
The SHOPIFY_STOREFRONT_API_URL export is gone too — hydrogen builds the
endpoint from storeDomain and apiVersion, and nothing else used it.
No behaviour change intended: same documents, same env var names, same
2025-07 API pin, same caching split between the two clients.
yarn typecheck passes with 0 errors. Verified against mock.shop: build
prerenders the policy pages, and in the browser product grid, search,
collection filters, cart restore, quantity update and discount-code
apply all work with no console errors. Customer account flows remain
untested — they need real credentials.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01JaxgqPbFxLsSuLPZom2kdC
Replaces the hand-rolled shopifyFetch wrapper and raw query strings with
the hydrogen preview package (0.0.0-preview-116d5d7-20260730141607), the
same build pinned in hydrogen-preview/.
- services/shopify/client: createStorefrontClient({type: "public"}) with a
static request context. Two module-scoped clients — uncached for carts,
products and customers; revalidate-3600 for shop policies — using the
client's custom fetch option to carry Next's caching hints.
- graphql/*: every document wrapped in gql(), fragments composed via the
second argument instead of string interpolation, and $country/$language
declared with @inContext so hydrogen injects them.
- shopifyFetch keeps its {query, variables} call shape so call sites are
unchanged, but is now generic over the document, so data is inferred. It
re-raises GraphQL errors, which hydrogen returns rather than throws.
Env var names, the 2025-07 API version pin, and the client-side fetching
architecture are unchanged.
Turning on type coverage surfaced real defects, not just annotations:
- hydrogen gql check caught $discountCodes: [String!] used where the field
requires [String!]!.
- Cart and customer mutation payloads are nullable and were dereferenced
unconditionally, so a failed mutation threw a TypeError. Adds a shared
unwrapCartPayload helper (collapsing five copies of the same userErrors
check) and explicit null handling in the customer service, so a null
payload reads as an error rather than success with no errors.
- Search results are a Product | Page | Article union; adds __typename to
the queries and narrows on it.
- Widens nullable fields (altText, image, customer.email, totalTaxAmount)
in the domain interfaces and in the structural duplicates some
components declare locally.
Adds a typecheck script (tsc --noEmit && hydrogen gql check); it passes
with 0 errors. Two deprecation warnings are left alone as acting on them
would change behaviour: ProductOption.values and CartCost.totalTaxAmount.
Verified against mock.shop: build prerenders the policy pages through the
cached client, and in the browser the product grid, search with facets,
collection filter round-trip, add-to-cart and quantity update all work.
Customer account flows are untested — they need real credentials.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01JaxgqPbFxLsSuLPZom2kdC
Shopify gives every single-variant product one option named Title with the
lone value Default Title. It isn't a real choice, so filter it out of the
product detail options, the cart line summaries, and the payload the store
assistant sees. Variant matching still reads the raw selectedOptions, so
single-SKU products keep resolving their variant.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EuRVxuyMUTzWKXW8P5Tn8A
- Storefront customer operations in graphql/customer.js and a server-safe
services/shopify/customer.ts
- Session held in an httpOnly, sameSite=lax cookie set by the
/api/account handlers; the access token never reaches client JS
- Pages: /account/login, /register, /recover, /reset/[id]/[token] and
/activate/[id]/[token] for Shopify's emailed links
- /account renders order history as master-detail on one screen, since
the Storefront API has no standalone order-by-id query for customers
- Header user icon: links to sign-in when signed out, otherwise a menu
with name, email, order history, and sign out
- Login errors are collapsed and password recovery responds identically
for known and unknown emails, so neither form enumerates accounts
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016jWbNNJLksC1QG8z8845FX
- /api/chat streams via AI SDK v7 through OpenRouter (OPENROUTER_API_KEY),
with a store-specific system prompt and five read-only tools:
searchCatalogue, getProductDetails, listCollections,
getCollectionProducts, browseProducts
- Sidebar assistant on the right that opens from a launcher and expands,
built on ai-elements (conversation, message, prompt-input, tool) with
shimmer on in-flight tool calls
- Extract services/shopify/catalog.ts so the Storefront fetchers have no
React imports and can run in a Route Handler; the client hooks now
re-export from it
- ai-elements pulled in the canonical shadcn primitives, replacing the
hand-rolled command/dialog/button variants; search dialog moved to the
cmdk-based Command and CommandDialog forwards shouldFilter
- Pin shiki to ^3.19.0 to match streamdown and drop the duplicate copy
- Add .env.example documenting the required env vars
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016jWbNNJLksC1QG8z8845FX
