Replace storefront client and price formatting with @shopify/hydrogen preview

[blurrah]

What

Evaluates Shopify's new framework-agnostic @shopify/hydrogen preview SDK (0.0.0-preview-0c3bff8) by replacing everything in the template it can substitute like-for-like. No new features — pure replacement, so we can measure how it performs before deciding on deeper adoption.

Replaced

Storefront API client (lib/shopify/storefront.ts)

• Now built on Hydrogen's createStorefrontClient (type: "public"); @shopify/storefront-api-client removed from dependencies.
• The storefront.request<T>() call-site contract is unchanged — all ~35 operation call sites, codegen, fragments, and transforms are untouched.
• Hydrogen injects $country/$language from its creation-time i18n config, overriding per-request variables — so the wrapper caches one client per country/language pair and selects it from the request's variables, preserving the per-call locale flow and the multi-locale upgrade path.
• Transport failures now throw typed StorefrontApiError/StorefrontTimeoutError (30s default timeout); GraphQL errors still resolve to { data, errors }. assertStorefrontOk updated for the GraphQLFormattedError[] shape.
• The ?operation= debug annotation, brotli header, and DEBUG_SHOPIFY timing log survive via Hydrogen's fetch config option. Env vars unchanged.

All price formatting

• formatPrice (lib/utils.ts, lib/markdown/utils.ts) and the Price component now delegate to Hydrogen's formatMoney with currencyDisplay: "narrowSymbol". Output verified byte-identical to the previous Intl.NumberFormat usage.

Evaluated, deliberately not replaced

• Cart store / server handlers — Hydrogen's model is a client-side store + /api/cart endpoints with a client-readable cookie; swapping would re-architect the server-action + cache-tag cart (discount apply/revert, locale sync, invalidateCartCache), not replace it. Candidate for a follow-up PR.
• getSelectedProductOptions — doesn't replicate the template's case-insensitive option canonicalization for PDP URLs.
• parseProductFilters — matches the template's parsing almost exactly but isn't exported from the package's server entry.
• Collection store, analytics bus, Shop Pay button — client-side re-architectures or net-new features.

Also in this PR

• Vendored the package's 12 agent skills into apps/template/.claude/skills via pnpm exec hydrogen setup (their setup CLI works when run from the app root).
• Updated docs (reference/storefront-api.mdx, shopify/writing-shopify-queries.mdx), the shopify-graphql-reference skill file table, and added a template-rollout-log entry (hydrogen-preview-client).

Testing

• tsc --noEmit, oxlint, oxfmt --check pass.
• pnpm build passes — partial-prerender pages (PDP, collections) made live SFAPI calls through the Hydrogen client at build time.
• Production-server smoke test: /, /products/[handle], /collections/all, /cart, /search?q=jacket all 200 with prices rendering through formatMoney.

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
shop-docs	Ready	Preview, Comment	Jul 7, 2026 5:36pm
shop-template	Ready	Preview, Comment, Open in v0	Jul 7, 2026 5:36pm

[socket-security]

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	npm/​@​shopify/​hydrogen@​0.0.0-preview-0c3bff8-20260618001533

View full report