@tanstack/create 0.65.0 → 0.66.0

package/CHANGELOG.md

@@ -1,5 +1,69 @@
 # @tanstack/create
 
+## 0.66.0
+
+### Minor Changes
+
+- feat(cli, create): add Shopify storefront add-on + storefront template ([`814d222`](https://github.com/TanStack/cli/commit/814d222ac04e839eabe56abce5dcbe66d751c5d8))
+
+  Headless Shopify support for TanStack Start apps, scaffold-ready and
+  runtime-portable. The pitch: prove that TanStack Start is a first-class
+  target for Shopify, not just Next.js Commerce or Hydrogen.
+
+  **`shopify` add-on** — additive. `tanstack add shopify` mounts `/shop/*`
+  routes alongside an existing app without touching the home page. Includes:
+
+  - Storefront API client (server-only fetch via `createServerFn`, public
+    token by default + optional private token for higher rate limits and
+    buyer-IP forwarding).
+  - Hand-written GraphQL queries with hydrogen-react types (type-only;
+    zero runtime weight).
+  - httpOnly cookie cart (`tanstack_cart_id`) + React Query single-key
+    cache + optimistic updates with module-level mutation counter to
+    batch invalidations during rapid clicks.
+  - Hydrogen-demo parity routes: shop landing, product detail (with
+    variants + availability), collections, cart, search, Shopify CMS
+    pages, policies.
+  - Hydrogen-stock UI components (ProductCard, VariantSelector,
+    AddToCartButton, CartLineItem, CartSummary, ShopImage with CDN
+    transforms, Money via Intl) themed with six CSS custom properties
+    for easy reskinning.
+  - Header cart-count badge via the `header-user` integration slot.
+  - Shopify-hosted checkout (redirect to `cart.checkoutUrl`).
+  - **Optional Customer Account API** behind a `customerAccount` select
+    option. Hand-rolled OAuth 2.1 PKCE with `.well-known` discovery
+    cached in module memory (no usable npm client exists yet),
+    HMAC-signed httpOnly session cookies (HS256), lazy token refresh,
+    account dashboard / orders / order detail / addresses routes — all
+    EJS-guarded so the files only emit when enabled.
+
+  **`shopify-storefront` template** — storefront-first.
+  `tanstack create my-shop --template shopify-storefront` cascades the
+  `shopify` add-on (which cascades `tanstack-query`) and replaces the
+  home route with a polished landing (hero + featured collections + best
+  sellers grid).
+
+  **Zero-config first run.** Defaults to Shopify's public Hydrogen demo
+  store (`hydrogen-preview.myshopify.com`) so the storefront renders
+  real products immediately. Override the four env vars in `.env.local`
+  (or your deploy target's dashboard) to point at your store. Demo
+  defaults are baked into source as fallbacks, so the experience doesn't
+  break when a runtime doesn't load `.env` files into `process.env`.
+
+  **Portable.** Cookie ops via `@tanstack/react-start/server`; crypto via
+  Web Crypto (`crypto.subtle`); generic `CDN-Cache-Control` for browse
+  (`s-maxage=300, stale-while-revalidate=600`) and `private, no-store`
+  for cart. Works on Node, Cloudflare Workers, Shopify Oxygen (just
+  Workers), Vercel, Netlify, Bun, Deno.
+
+  **Header layout fix.** While the cart-count badge is the new
+  right-aligned action, the base scaffold's `Header` was placing the
+  social icons left-of-center on `sm+`. Reordered the JSX so navigation
+  sits between the logo and the right-side actions in DOM order, with
+  one mobile-only `order-3` to keep `flex-wrap` putting nav on its own
+  row. Result: logo → nav → (auto-spaced) → cart/social/theme on every
+  breakpoint, and a more sensible reading order for screen readers.
+
 ## 0.65.0
 
 ### Minor Changes

package/dist/frameworks/react/add-ons/shopify/README.md

@@ -0,0 +1,86 @@
+# Shopify
+
+Headless Shopify storefront for TanStack Start. Mounts `/shop/*` routes
+alongside your existing app — your home page stays untouched.
+
+The default `.env.local` points at Shopify's public Hydrogen demo store, so the
+storefront renders real products on first run with zero setup.
+
+## Routes
+
+| Route                          | What it does                                |
+|--------------------------------|---------------------------------------------|
+| `/shop`                        | Shop landing — featured products + collections |
+| `/shop/products/$handle`       | Product detail (variants, images, options)  |
+| `/shop/collections/$handle`    | Collection grid with sort + pagination      |
+| `/shop/cart`                   | Cart line items, discount codes, checkout   |
+| `/shop/search`                 | Product search                              |
+| `/shop/pages/$handle`          | Shopify CMS pages (about, etc.)             |
+| `/shop/policies/$handle`       | Privacy, refund, terms, shipping            |
+
+If you opted into customer accounts during scaffold:
+
+| Route                                | What it does                       |
+|--------------------------------------|------------------------------------|
+| `/shop/account/login`                | Kick off Shopify OAuth             |
+| `/shop/account/callback`             | OAuth callback handler             |
+| `/shop/account/logout`               | End the customer session           |
+| `/shop/account`                      | Dashboard                          |
+| `/shop/account/orders`               | Order history                      |
+| `/shop/account/orders/$id`           | Order detail                       |
+| `/shop/account/addresses`            | Manage saved addresses             |
+
+## Connect your store
+
+1. In Shopify admin, go to **Settings > Apps and sales channels > Develop apps**.
+2. Create a new app, enable the **Storefront API**, and copy the public access token.
+3. Set in `.env.local`:
+   ```
+   SHOPIFY_STORE_DOMAIN=your-store.myshopify.com
+   SHOPIFY_PUBLIC_STOREFRONT_TOKEN=...
+   ```
+4. (Optional) For higher rate limits + buyer-IP forwarding, also create a private
+   token and set `SHOPIFY_PRIVATE_STOREFRONT_TOKEN`.
+
+## Enable customer accounts
+
+If `customerAccount=enabled` was selected during scaffold:
+
+1. In Shopify admin, go to **Settings > Customer accounts > Headless**.
+2. Register a public client. Add `http://localhost:3000/shop/account/callback`
+   *and* your production callback URL to the redirect URIs.
+3. Copy the Client ID and Shop ID into `.env.local`:
+   ```
+   SHOPIFY_CUSTOMER_ACCOUNT_CLIENT_ID=...
+   SHOPIFY_CUSTOMER_ACCOUNT_SHOP_ID=...
+   SHOPIFY_SESSION_SECRET=$(openssl rand -hex 32)
+   ```
+
+The Hydrogen demo store doesn't have customer accounts configured, so the
+default demo creds won't work for `/shop/account/*` — you'll need a real store.
+
+## Architecture
+
+- **Storefront API client** — server-only fetch in `src/server/shopify/storefront-client.ts`.
+  All product/cart reads go through the server (private token never reaches the browser).
+- **Cart state** — Cart ID stored in an httpOnly cookie (`tanstack_cart_id`). React
+  Query owns the cache (single key `['shopify', 'cart']`); optimistic updates with
+  a module-level mutation counter to batch invalidations.
+- **GraphQL queries** — hand-written strings in `src/lib/shopify/queries.ts`, types
+  sliced from `@shopify/hydrogen-react/storefront-api-types` (type-only import; zero runtime).
+- **Customer accounts** — hand-rolled OAuth 2.1 PKCE with `.well-known` discovery
+  (no usable npm client exists yet). Tokens in a signed httpOnly cookie.
+- **Checkout** — redirects to `cart.checkoutUrl` (Shopify-hosted).
+
+## Deployment
+
+Works anywhere TanStack Start runs:
+
+- **Node** — `npm run build && npm start`
+- **Cloudflare Workers / Shopify Oxygen** — Oxygen is just Workers under the hood;
+  build with the Workers preset and deploy to either platform.
+- **Vercel / Netlify** — set the env vars in the dashboard.
+- **Bun, Deno** — supported via Start's adapters.
+
+For the customer-account flow, register both your local *and* production
+callback URLs in the Shopify admin's headless app config.

package/dist/frameworks/react/add-ons/shopify/assets/_dot_env.local.append

@@ -0,0 +1,19 @@
+# ─── Shopify ─────────────────────────────────────────────────────────────────
+# These defaults point to Shopify's public Hydrogen demo store so the storefront
+# works on first run with zero config. Replace with your store's values to go live.
+# Get tokens at: Shopify admin > Settings > Apps and sales channels > Develop apps.
+SHOPIFY_STORE_DOMAIN=hydrogen-preview.myshopify.com
+SHOPIFY_STOREFRONT_API_VERSION=2026-01
+SHOPIFY_PUBLIC_STOREFRONT_TOKEN=3b580e70970c4528da70c98e097c2fa0
+# Optional — set to a private storefront token for higher rate limits + buyer-IP forwarding.
+SHOPIFY_PRIVATE_STOREFRONT_TOKEN=
+
+# ─── Shopify Customer Account API ────────────────────────────────────────────
+# Required only if you opted into customer accounts during scaffold.
+# Register a public client in Shopify admin > Settings > Customer accounts > Headless,
+# then paste the client ID and your numeric shop ID below.
+SHOPIFY_CUSTOMER_ACCOUNT_CLIENT_ID=
+SHOPIFY_CUSTOMER_ACCOUNT_SHOP_ID=
+SHOPIFY_CUSTOMER_ACCOUNT_REDIRECT_URI=http://localhost:3000/shop/account/callback
+# 32+ random chars, e.g. `openssl rand -hex 32`. Used to sign customer session cookies.
+SHOPIFY_SESSION_SECRET=

package/dist/frameworks/react/add-ons/shopify/assets/src/components/shop/account-nav.tsx.ejs

@@ -0,0 +1,41 @@
+<% if (addOnOption.shopify.customerAccount !== 'enabled') { ignoreFile(); return; } %>
+import { Link } from '@tanstack/react-router'
+
+const ITEMS = [
+  { to: '/shop/account', label: 'Overview', exact: true },
+  { to: '/shop/account/orders', label: 'Orders', exact: false },
+  { to: '/shop/account/addresses', label: 'Addresses', exact: false },
+] as const
+
+export function AccountNav() {
+  return (
+    <nav className="flex flex-col gap-1 text-sm">
+      {ITEMS.map((item) => (
+        <Link
+          key={item.to}
+          to={item.to}
+          activeOptions={{ exact: item.exact }}
+          className="rounded-md px-2 py-1.5 text-[var(--storefront-fg-muted)] hover:bg-[var(--storefront-line)]/40 hover:text-[var(--storefront-fg)]"
+          activeProps={{
+            className:
+              'rounded-md px-2 py-1.5 bg-[var(--storefront-line)]/60 text-[var(--storefront-fg)] font-medium',
+          }}
+        >
+          {item.label}
+        </Link>
+      ))}
+      <form
+        action="/shop/account/logout"
+        method="post"
+        className="mt-4 border-t border-[var(--storefront-line)] pt-4"
+      >
+        <button
+          type="submit"
+          className="rounded-md px-2 py-1.5 text-left text-sm text-[var(--storefront-fg-muted)] hover:text-[var(--storefront-fg)]"
+        >
+          Sign out
+        </button>
+      </form>
+    </nav>
+  )
+}

package/dist/frameworks/react/add-ons/shopify/assets/src/components/shop/add-to-cart-button.tsx

@@ -0,0 +1,48 @@
+import { useAddToCart } from '#/hooks/use-cart'
+import type { ProductDetail, ProductDetailVariant } from '#/lib/shopify/queries'
+
+type AddToCartButtonProps = {
+  product: ProductDetail
+  variant: ProductDetailVariant | undefined
+  quantity?: number
+}
+
+export function AddToCartButton({
+  product,
+  variant,
+  quantity = 1,
+}: AddToCartButtonProps) {
+  const { mutate, isPending } = useAddToCart()
+  const disabled = !variant || !variant.availableForSale || isPending
+
+  return (
+    <button
+      type="button"
+      disabled={disabled}
+      onClick={() => {
+        if (!variant) return
+        mutate({
+          variantId: variant.id,
+          quantity,
+          line: {
+            productTitle: product.title,
+            productHandle: product.handle,
+            variantTitle: variant.title,
+            price: variant.price,
+            image: variant.image ?? product.images.nodes[0] ?? null,
+            selectedOptions: variant.selectedOptions,
+          },
+        })
+      }}
+      className="w-full rounded-full bg-[var(--storefront-accent)] px-6 py-3.5 text-sm font-medium text-[var(--storefront-accent-fg)] transition disabled:cursor-not-allowed disabled:opacity-50 hover:opacity-90"
+    >
+      {!variant
+        ? 'Select options'
+        : !variant.availableForSale
+          ? 'Sold out'
+          : isPending
+            ? 'Adding…'
+            : 'Add to cart'}
+    </button>
+  )
+}

package/dist/frameworks/react/add-ons/shopify/assets/src/components/shop/cart-line-item.tsx

@@ -0,0 +1,94 @@
+import { Link } from '@tanstack/react-router'
+
+import { Money } from '#/components/shop/money'
+import { ShopImage } from '#/components/shop/shop-image'
+import { useRemoveCartLine, useUpdateCartLine } from '#/hooks/use-cart'
+import type { CartLineDetail } from '#/lib/shopify/queries'
+
+type CartLineItemProps = {
+  line: CartLineDetail
+}
+
+export function CartLineItem({ line }: CartLineItemProps) {
+  const update = useUpdateCartLine()
+  const remove = useRemoveCartLine()
+  const merch = line.merchandise
+
+  return (
+    <li className="flex gap-4 border-b border-[var(--storefront-line)] py-6">
+      <Link
+        to="/shop/products/$handle"
+        params={{ handle: merch.product.handle }}
+        className="flex-shrink-0"
+      >
+        <ShopImage
+          src={merch.image?.url}
+          alt={merch.image?.altText ?? merch.product.title}
+          width={120}
+          height={150}
+          className="h-[150px] w-[120px] rounded-md object-cover"
+        />
+      </Link>
+      <div className="flex flex-1 flex-col gap-2">
+        <div className="flex items-start justify-between gap-4">
+          <div>
+            <Link
+              to="/shop/products/$handle"
+              params={{ handle: merch.product.handle }}
+              className="text-base font-medium no-underline text-[var(--storefront-fg)]"
+            >
+              {merch.product.title}
+            </Link>
+            {merch.title && merch.title !== 'Default Title' && (
+              <p className="text-sm text-[var(--storefront-fg-muted)]">
+                {merch.selectedOptions.map((o) => o.value).join(' · ')}
+              </p>
+            )}
+          </div>
+          <Money
+            amount={line.cost.totalAmount.amount}
+            currencyCode={line.cost.totalAmount.currencyCode}
+            className="text-base font-medium"
+          />
+        </div>
+        <div className="mt-auto flex items-center justify-between gap-4">
+          <div className="inline-flex items-center rounded-full border border-[var(--storefront-line)]">
+            <button
+              type="button"
+              aria-label="Decrease quantity"
+              disabled={update.isPending || line.quantity <= 1}
+              onClick={() =>
+                update.mutate({ lineId: line.id, quantity: line.quantity - 1 })
+              }
+              className="px-3 py-1.5 text-base disabled:opacity-40"
+            >
+              −
+            </button>
+            <span className="min-w-[2rem] text-center text-sm">
+              {line.quantity}
+            </span>
+            <button
+              type="button"
+              aria-label="Increase quantity"
+              disabled={update.isPending}
+              onClick={() =>
+                update.mutate({ lineId: line.id, quantity: line.quantity + 1 })
+              }
+              className="px-3 py-1.5 text-base disabled:opacity-40"
+            >
+              +
+            </button>
+          </div>
+          <button
+            type="button"
+            onClick={() => remove.mutate({ lineId: line.id })}
+            disabled={remove.isPending}
+            className="text-sm text-[var(--storefront-fg-muted)] underline underline-offset-4 hover:text-[var(--storefront-fg)] disabled:opacity-40"
+          >
+            Remove
+          </button>
+        </div>
+      </div>
+    </li>
+  )
+}

package/dist/frameworks/react/add-ons/shopify/assets/src/components/shop/cart-summary.tsx

@@ -0,0 +1,111 @@
+import { useState } from 'react'
+
+import { Money } from '#/components/shop/money'
+import {
+  useApplyDiscountCode,
+  useRemoveDiscountCode,
+} from '#/hooks/use-cart'
+import type { CartDetail } from '#/lib/shopify/queries'
+
+type CartSummaryProps = {
+  cart: CartDetail
+}
+
+export function CartSummary({ cart }: CartSummaryProps) {
+  const [code, setCode] = useState('')
+  const apply = useApplyDiscountCode()
+  const remove = useRemoveDiscountCode()
+  const appliedCode = cart.discountCodes.find((c) => c.applicable)
+
+  return (
+    <aside className="flex flex-col gap-4 rounded-2xl border border-[var(--storefront-line)] p-6">
+      <h2 className="text-lg font-medium">Order summary</h2>
+
+      <div className="flex justify-between text-sm">
+        <span>Subtotal</span>
+        <Money
+          amount={cart.cost.subtotalAmount.amount}
+          currencyCode={cart.cost.subtotalAmount.currencyCode}
+        />
+      </div>
+      {cart.cost.totalTaxAmount && Number(cart.cost.totalTaxAmount.amount) > 0 && (
+        <div className="flex justify-between text-sm text-[var(--storefront-fg-muted)]">
+          <span>Estimated tax</span>
+          <Money
+            amount={cart.cost.totalTaxAmount.amount}
+            currencyCode={cart.cost.totalTaxAmount.currencyCode}
+          />
+        </div>
+      )}
+      <p className="text-sm text-[var(--storefront-fg-muted)]">
+        Shipping calculated at checkout.
+      </p>
+
+      <form
+        onSubmit={(e) => {
+          e.preventDefault()
+          if (code.trim()) {
+            apply.mutate(
+              { code: code.trim() },
+              { onSuccess: () => setCode('') },
+            )
+          }
+        }}
+        className="flex flex-col gap-2"
+      >
+        <div className="flex gap-2">
+          <input
+            type="text"
+            value={code}
+            onChange={(e) => setCode(e.target.value)}
+            placeholder="Discount code"
+            className="min-w-0 flex-1 rounded-full border border-[var(--storefront-line)] bg-transparent px-4 py-2 text-sm focus:border-[var(--storefront-accent)] focus:outline-none"
+          />
+          <button
+            type="submit"
+            disabled={apply.isPending || !code.trim()}
+            className="rounded-full border border-[var(--storefront-line)] px-4 py-2 text-sm font-medium hover:border-[var(--storefront-accent)] disabled:opacity-40"
+          >
+            Apply
+          </button>
+        </div>
+        {apply.error && (
+          <p className="text-xs text-red-600">{(apply.error as Error).message}</p>
+        )}
+        {appliedCode && (
+          <div className="flex items-center justify-between rounded-full bg-[var(--storefront-line)]/40 px-4 py-2 text-xs">
+            <span>
+              Applied: <strong>{appliedCode.code}</strong>
+            </span>
+            <button
+              type="button"
+              onClick={() => remove.mutate()}
+              disabled={remove.isPending}
+              className="underline underline-offset-2 disabled:opacity-40"
+            >
+              Remove
+            </button>
+          </div>
+        )}
+      </form>
+
+      <div className="flex justify-between border-t border-[var(--storefront-line)] pt-4 text-base font-medium">
+        <span>Total</span>
+        <Money
+          amount={cart.cost.totalAmount.amount}
+          currencyCode={cart.cost.totalAmount.currencyCode}
+        />
+      </div>
+
+      <a
+        href={cart.checkoutUrl}
+        className="block w-full rounded-full bg-[var(--storefront-accent)] px-6 py-3.5 text-center text-sm font-medium text-[var(--storefront-accent-fg)] no-underline transition hover:opacity-90"
+      >
+        Checkout
+      </a>
+      <p className="text-center text-xs text-[var(--storefront-fg-muted)]">
+        Secure checkout powered by Shopify
+      </p>
+    </aside>
+  )
+}

package/dist/frameworks/react/add-ons/shopify/assets/src/components/shop/empty-state.tsx

@@ -0,0 +1,29 @@
+import { Link } from '@tanstack/react-router'
+import type { ReactNode } from 'react'
+
+type EmptyStateProps = {
+  title: string
+  description?: string
+  cta?: { label: string; to: string }
+  children?: ReactNode
+}
+
+export function EmptyState({ title, description, cta, children }: EmptyStateProps) {
+  return (
+    <div className="flex flex-col items-center gap-4 rounded-2xl border border-dashed border-[var(--storefront-line)] px-6 py-16 text-center">
+      <h2 className="text-xl font-medium">{title}</h2>
+      {description && (
+        <p className="max-w-md text-[var(--storefront-fg-muted)]">{description}</p>
+      )}
+      {children}
+      {cta && (
+        <Link
+          to={cta.to}
+          className="rounded-full border border-[var(--storefront-fg)] px-5 py-2 text-sm font-medium no-underline text-[var(--storefront-fg)]"
+        >
+          {cta.label}
+        </Link>
+      )}
+    </div>
+  )
+}

package/dist/frameworks/react/add-ons/shopify/assets/src/components/shop/money.tsx

@@ -0,0 +1,11 @@
+import { formatMoney } from '#/lib/shopify/format'
+
+type MoneyProps = {
+  amount: string | number
+  currencyCode: string
+  className?: string
+}
+
+export function Money({ amount, currencyCode, className }: MoneyProps) {
+  return <span className={className}>{formatMoney(amount, currencyCode)}</span>
+}

package/dist/frameworks/react/add-ons/shopify/assets/src/components/shop/product-card.tsx

@@ -0,0 +1,74 @@
+import { Link } from '@tanstack/react-router'
+
+import { Money } from '#/components/shop/money'
+import { ShopImage } from '#/components/shop/shop-image'
+import type { ProductListItem } from '#/lib/shopify/queries'
+
+type ProductCardProps = {
+  product: ProductListItem
+}
+
+export function ProductCard({ product }: ProductCardProps) {
+  const minPrice = product.priceRange.minVariantPrice
+  const maxPrice = product.priceRange.maxVariantPrice
+  const compareAt = product.compareAtPriceRange.minVariantPrice
+  const onSale =
+    Number(compareAt.amount) > 0 &&
+    Number(compareAt.amount) > Number(minPrice.amount)
+  const soldOut = !product.variants.nodes.some((v) => v.availableForSale)
+
+  return (
+    <Link
+      to="/shop/products/$handle"
+      params={{ handle: product.handle }}
+      className="group flex flex-col gap-3 no-underline text-[var(--storefront-fg)]"
+    >
+      <div
+        className="relative overflow-hidden bg-[var(--storefront-line)]"
+        style={{ aspectRatio: '4 / 5', borderRadius: 'var(--storefront-radius)' }}
+      >
+        <ShopImage
+          src={product.featuredImage?.url}
+          alt={product.featuredImage?.altText ?? product.title}
+          width={600}
+          height={750}
+          sizes="(min-width: 1024px) 25vw, (min-width: 640px) 33vw, 50vw"
+          className="h-full w-full object-cover transition-transform duration-500 group-hover:scale-[1.03]"
+        />
+        {soldOut && (
+          <span className="absolute left-3 top-3 rounded-full bg-[var(--storefront-bg)]/90 px-2.5 py-1 text-xs font-medium uppercase tracking-wide">
+            Sold out
+          </span>
+        )}
+        {!soldOut && onSale && (
+          <span className="absolute left-3 top-3 rounded-full bg-[var(--storefront-accent)] px-2.5 py-1 text-xs font-medium uppercase tracking-wide text-[var(--storefront-accent-fg)]">
+            Sale
+          </span>
+        )}
+      </div>
+      <div className="flex flex-col gap-1">
+        <h3 className="text-sm font-medium leading-snug">{product.title}</h3>
+        <p className="text-sm text-[var(--storefront-fg-muted)]">
+          {onSale && (
+            <span className="mr-2 line-through">
+              <Money
+                amount={compareAt.amount}
+                currencyCode={compareAt.currencyCode}
+              />
+            </span>
+          )}
+          <Money amount={minPrice.amount} currencyCode={minPrice.currencyCode} />
+          {Number(maxPrice.amount) > Number(minPrice.amount) && (
+            <>
+              {' – '}
+              <Money
+                amount={maxPrice.amount}
+                currencyCode={maxPrice.currencyCode}
+              />
+            </>
+          )}
+        </p>
+      </div>
+    </Link>
+  )
+}

package/dist/frameworks/react/add-ons/shopify/assets/src/components/shop/product-grid.tsx

@@ -0,0 +1,24 @@
+import { ProductCard } from '#/components/shop/product-card'
+import type { ProductListItem } from '#/lib/shopify/queries'
+
+type ProductGridProps = {
+  products: ReadonlyArray<ProductListItem>
+}
+
+export function ProductGrid({ products }: ProductGridProps) {
+  if (products.length === 0) {
+    return (
+      <p className="py-16 text-center text-[var(--storefront-fg-muted)]">
+        No products yet.
+      </p>
+    )
+  }
+
+  return (
+    <div className="grid grid-cols-2 gap-x-4 gap-y-10 sm:grid-cols-3 lg:grid-cols-4">
+      {products.map((product) => (
+        <ProductCard key={product.id} product={product} />
+      ))}
+    </div>
+  )
+}

package/dist/frameworks/react/add-ons/shopify/assets/src/components/shop/shop-image.tsx

@@ -0,0 +1,57 @@
+import { shopifyImageUrl } from '#/lib/shopify/format'
+
+type ShopImageProps = {
+  src: string | null | undefined
+  alt: string | null | undefined
+  width: number
+  height?: number
+  className?: string
+  sizes?: string
+  loading?: 'eager' | 'lazy'
+}
+
+export function ShopImage({
+  src,
+  alt,
+  width,
+  height,
+  className,
+  sizes,
+  loading = 'lazy',
+}: ShopImageProps) {
+  if (!src) {
+    return (
+      <div
+        aria-hidden
+        className={className}
+        style={{
+          background: 'var(--storefront-line)',
+          aspectRatio: height ? `${width} / ${height}` : '1',
+        }}
+      />
+    )
+  }
+
+  const transformed = shopifyImageUrl(src, { width, height, format: 'webp' })
+  const srcSet = [1, 2]
+    .map((dpr) => {
+      const w = width * dpr
+      const h = height ? height * dpr : undefined
+      return `${shopifyImageUrl(src, { width: w, height: h, format: 'webp' })} ${dpr}x`
+    })
+    .join(', ')
+
+  return (
+    <img
+      src={transformed}
+      srcSet={srcSet}
+      sizes={sizes}
+      alt={alt ?? ''}
+      width={width}
+      height={height}
+      loading={loading}
+      decoding="async"
+      className={className}
+    />
+  )
+}