@tanstack/create 0.65.0 → 0.66.0

package/dist/frameworks/react/examples/shopify-storefront/assets/src/routes/index.tsx

@@ -0,0 +1,65 @@
+import { Link, createFileRoute } from '@tanstack/react-router'
+
+import '#/components/shop/shop.css'
+import { ProductGrid } from '#/components/shop/product-grid'
+import { FeaturedCollections } from '#/components/FeaturedCollections'
+import { ShopHero } from '#/components/ShopHero'
+import {
+  getCollections,
+  getProducts,
+  getShop,
+} from '#/server/shopify/catalog.functions'
+
+export const Route = createFileRoute('/')({
+  loader: async () => {
+    const [shop, collections, products] = await Promise.all([
+      getShop(),
+      getCollections(),
+      getProducts({ data: { first: 8, sortKey: 'BEST_SELLING' } }),
+    ])
+    return { shop, collections, featured: products.nodes }
+  },
+  head: ({ loaderData }) => ({
+    meta: loaderData
+      ? [
+          { title: loaderData.shop.name },
+          { name: 'description', content: loaderData.shop.description ?? '' },
+        ]
+      : [],
+  }),
+  component: HomePage,
+})
+
+function HomePage() {
+  const { shop, collections, featured } = Route.useLoaderData()
+
+  return (
+    <div className="shop-root min-h-screen">
+      <ShopHero
+        title={shop.name}
+        tagline={shop.description ?? 'A TanStack Start + Shopify storefront.'}
+      />
+
+      {collections.length > 0 && (
+        <section className="mx-auto max-w-7xl px-4 pb-20 sm:px-6 lg:px-8">
+          <FeaturedCollections collections={collections.slice(0, 3)} />
+        </section>
+      )}
+
+      <section className="mx-auto max-w-7xl px-4 pb-24 sm:px-6 lg:px-8">
+        <div className="mb-8 flex items-baseline justify-between">
+          <h2 className="text-2xl font-medium tracking-tight sm:text-3xl">
+            Best sellers
+          </h2>
+          <Link
+            to="/shop"
+            className="text-sm underline underline-offset-4 hover:opacity-80"
+          >
+            Shop all →
+          </Link>
+        </div>
+        <ProductGrid products={featured} />
+      </section>
+    </div>
+  )
+}

package/dist/frameworks/react/examples/shopify-storefront/info.json

@@ -0,0 +1,18 @@
+{
+  "name": "Shopify Storefront",
+  "description": "A polished Shopify storefront starter — TanStack Start + Shopify Storefront API + optional customer accounts. Hosted checkout, deploy anywhere.",
+  "phase": "example",
+  "modes": ["file-router"],
+  "type": "example",
+  "category": "other",
+  "color": "#5A31F4",
+  "priority": 5,
+  "link": "https://shopify.dev/docs/storefronts/headless",
+  "dependsOn": ["shopify"],
+  "default": true,
+  "routes": [
+    { "url": "/", "path": "src/routes/index.tsx", "jsName": "ShopHome" }
+  ],
+  "integrations": [],
+  "variables": []
+}

package/dist/frameworks/react/examples/shopify-storefront/package.json

@@ -0,0 +1,3 @@
+{
+  "dependencies": {}
+}

package/dist/frameworks/react/project/base/src/components/Header.tsx.ejs

@@ -32,7 +32,40 @@ export default function Header() {
           </Link>
         </h2>
 
-        <div className="ml-auto flex items-center gap-1.5 sm:ml-0 sm:gap-2">
+        <div className="order-3 flex w-full flex-wrap items-center gap-x-4 gap-y-1 pb-1 text-sm font-semibold sm:order-none sm:w-auto sm:flex-nowrap sm:pb-0">
+          <Link to="/" className="nav-link" activeProps={{ className: 'nav-link is-active' }}>
+            Home
+          </Link>
+          <Link
+            to="/about"
+            className="nav-link"
+            activeProps={{ className: 'nav-link is-active' }}
+          >
+            About
+          </Link>
+          <a
+            href="https://tanstack.com/start/latest/docs/framework/react/overview"
+            className="nav-link"
+            target="_blank"
+            rel="noreferrer"
+          >
+            Docs
+          </a>
+          <% if (demoRoutes.length > 0) { %><details className="relative w-full sm:w-auto">
+            <summary className="nav-link list-none cursor-pointer">Demos</summary>
+            <div className="mt-2 min-w-56 rounded-xl border border-[var(--line)] bg-[var(--header-bg)] p-2 shadow-lg sm:absolute sm:right-0">
+              <% for (const route of demoRoutes) { %><a
+                href="<%= route.url %>"
+                className="block rounded-lg px-3 py-2 text-sm text-[var(--sea-ink-soft)] no-underline transition hover:bg-[var(--link-bg-hover)] hover:text-[var(--sea-ink)]"
+              >
+                <%= route.name %>
+              </a>
+              <% } %>
+            </div>
+          </details><% } %>
+        </div>
+
+        <div className="ml-auto flex items-center gap-1.5 sm:gap-2">
           <a
             href="https://x.com/tan_stack"
             target="_blank"
@@ -65,39 +98,6 @@ export default function Header() {
           <% } %>
           <ThemeToggle />
         </div>
-
-        <div className="order-3 flex w-full flex-wrap items-center gap-x-4 gap-y-1 pb-1 text-sm font-semibold sm:order-2 sm:w-auto sm:flex-nowrap sm:pb-0">
-          <Link to="/" className="nav-link" activeProps={{ className: 'nav-link is-active' }}>
-            Home
-          </Link>
-          <Link
-            to="/about"
-            className="nav-link"
-            activeProps={{ className: 'nav-link is-active' }}
-          >
-            About
-          </Link>
-          <a
-            href="https://tanstack.com/start/latest/docs/framework/react/overview"
-            className="nav-link"
-            target="_blank"
-            rel="noreferrer"
-          >
-            Docs
-          </a>
-          <% if (demoRoutes.length > 0) { %><details className="relative w-full sm:w-auto">
-            <summary className="nav-link list-none cursor-pointer">Demos</summary>
-            <div className="mt-2 min-w-56 rounded-xl border border-[var(--line)] bg-[var(--header-bg)] p-2 shadow-lg sm:absolute sm:right-0">
-              <% for (const route of demoRoutes) { %><a
-                href="<%= route.url %>"
-                className="block rounded-lg px-3 py-2 text-sm text-[var(--sea-ink-soft)] no-underline transition hover:bg-[var(--link-bg-hover)] hover:text-[var(--sea-ink)]"
-              >
-                <%= route.name %>
-              </a>
-              <% } %>
-            </div>
-          </details><% } %>
-        </div>
       </nav>
     </header>
   )

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/create",
-  "version": "0.65.0",
+  "version": "0.66.0",
   "description": "TanStack Application Builder Engine",
   "type": "module",
   "main": "./dist/index.js",

package/src/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/src/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/src/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/src/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/src/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/src/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/src/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/src/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>
+}