@tanstack/create 0.64.0 → 0.66.0

package/CHANGELOG.md

@@ -1,5 +1,86 @@
 # @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
+
+- feat(cli, create): close the gap between `tanstack create` and shipping a real app ([#445](https://github.com/TanStack/cli/pull/445))
+
+  A bundle of UX improvements aimed at beginners (especially those coming from Next.js) and the AI agents they pair with:
+
+  - **Tailored post-creation next steps.** The scaffold completion message now lists the env vars you still need to fill in `.env.local`, links the docs for each shipping-critical integration you picked (auth, database, ORM, deployment), and surfaces the Intent-wired AGENTS.md / CLAUDE.md with concrete prompt examples.
+  - **Pre-creation review screen.** After interactive prompts, the CLI shows a categorized summary (auth, database, ORM, deploy, other) and asks for confirmation before writing files. Conflicting selections (two auth providers, two ORMs, etc.) are flagged in the same step.
+  - **`.env.example` generation.** A checked-in `.env.example` is now derived from the env-var schemas of selected add-ons, with descriptions and a `(required)` marker. Plays nicely with add-ons that ship their own `_dot_env.example.append`.
+  - **Better add-on descriptions.** Concept-first one-liners replace generic "Add X to your application." Reads like a menu instead of a list of brand names.
+  - **Deployment quickstarts.** Each `--deployment` host (Netlify, Cloudflare, Railway, Nitro) now contributes its own README section explaining the actual steps to ship — push, dashboard URL, env var sync.
+  - **Clerk demo route parity.** Clerk's scaffold now ships a proper sign-in flow (matching Better Auth's depth) using Clerk's prebuilt components, plus a richer README with route-protection patterns and a production checklist.
+  - **Intent install passes `--map`.** The auto-invoked `intent install` now writes explicit task→skill mappings into the agent config instead of relying on runtime discovery, so agents see directly which skill matches which task.
+  - **`tanstack clean-demos` command.** A new subcommand removes leftover `demo.*` and `example.*` files (and prunes empty `routes/demo`/`routes/example` directories) so a beginner can ship without the scaffold's training wheels.
+
 ## 0.64.0
 
 ### Minor Changes

package/dist/create-app.js

@@ -1,5 +1,5 @@
 import { basename, resolve } from 'node:path';
-import { isBase64 } from './file-helpers.js';
+import { isBase64, isDemoFilePath } from './file-helpers.js';
 import { formatCommand } from './utils.js';
 import { writeConfigFileToEnvironment } from './config-file.js';
 import { getPackageManagerScriptCommand, packageManagerInstall, translateExecuteCommand, } from './package-manager.js';
@@ -10,20 +10,6 @@ import { installShadcnComponents } from './integrations/shadcn.js';
 import { setupGit } from './integrations/git.js';
 import { setupIntent } from './integrations/intent.js';
 import { runSpecialSteps } from './special-steps/index.js';
-function isDemoFilePath(path) {
-    if (!path)
-        return false;
-    const normalized = path.replace(/\\/g, '/');
-    if (normalized.includes('/routes/demo/') ||
-        normalized.includes('/routes/example/')) {
-        return true;
-    }
-    const filename = normalized.split('/').pop() || '';
-    return (filename.startsWith('demo.') ||
-        filename.startsWith('demo-') ||
-        filename.startsWith('example.') ||
-        filename.startsWith('example-'));
-}
 function stripExamplesFromOptions(options) {
     if (options.includeExamples !== false) {
         return options;
@@ -240,6 +226,74 @@ async function seedEnvValues(environment, options) {
     }
     await environment.writeFile(envLocalPath, envContents);
 }
+async function writeEnvExample(environment, options) {
+    const envExamplePath = resolve(options.targetDir, '.env.example');
+    const existing = environment.exists(envExamplePath)
+        ? await environment.readFile(envExamplePath)
+        : '';
+    const declared = new Set();
+    for (const match of existing.matchAll(/^([A-Z_][A-Z0-9_]*)=/gm)) {
+        declared.add(match[1]);
+    }
+    const sections = [];
+    for (const addOn of options.chosenAddOns) {
+        const lines = [];
+        for (const envVar of addOn.envVars || []) {
+            if (declared.has(envVar.name))
+                continue;
+            declared.add(envVar.name);
+            if (envVar.description) {
+                const required = envVar.required ? ' (required)' : '';
+                lines.push(`# ${envVar.description}${required}`);
+            }
+            lines.push(`${envVar.name}=`);
+        }
+        if (lines.length > 0) {
+            sections.push(`# ${addOn.name}\n${lines.join('\n')}`);
+        }
+    }
+    if (sections.length === 0)
+        return;
+    const additions = sections.join('\n\n');
+    const newContent = existing
+        ? `${existing.trimEnd()}\n\n${additions}\n`
+        : `${additions}\n`;
+    await environment.writeFile(envExamplePath, newContent);
+}
+const SHIPPING_CATEGORIES = new Set(['auth', 'database', 'orm', 'deploy']);
+function buildNextSteps(options) {
+    const collectedEnv = new Set(Object.keys(options.envVarValues || {}));
+    const listedEnvVars = new Set();
+    const envVarLines = [];
+    const docLines = [];
+    for (const addOn of options.chosenAddOns) {
+        if (addOn.link && addOn.category && SHIPPING_CATEGORIES.has(addOn.category)) {
+            docLines.push(`  • ${addOn.name} (${addOn.category}) — ${addOn.link}`);
+        }
+        for (const envVar of addOn.envVars || []) {
+            if (listedEnvVars.has(envVar.name))
+                continue;
+            listedEnvVars.add(envVar.name);
+            const required = envVar.required ? ' (required)' : '';
+            const status = collectedEnv.has(envVar.name)
+                ? ' — already set from your input'
+                : ' — needs a value';
+            const desc = envVar.description ? ` — ${envVar.description}` : '';
+            envVarLines.push(`  • ${envVar.name}${required}${desc}${status}`);
+        }
+    }
+    const sections = [];
+    if (envVarLines.length > 0) {
+        sections.push(`Environment variables (review/fill in .env.local before deploying):\n${envVarLines.join('\n')}`);
+    }
+    if (docLines.length > 0) {
+        sections.push(`Docs for the integrations you picked:\n${docLines.join('\n')}`);
+    }
+    if (options.intent) {
+        sections.push(`Working with an AI agent? Your agent config (AGENTS.md / CLAUDE.md) was wired up by TanStack Intent\nwith explicit skill mappings for the libraries you installed. Try asking your agent:\n  • "migrate this Next.js page to TanStack Start"\n  • "add a protected /dashboard route"\n  • "show me how to use TanStack Router search params"`);
+    }
+    return sections.length > 0 ? `\nNext steps:\n\n${sections.join('\n\n')}\n` : '';
+}
 function report(environment, options) {
     const warnings = [];
     for (const addOn of options.chosenAddOns) {
@@ -268,12 +322,13 @@ ${environment.getErrors().join('\n')}`;
         ? ''
         : `% cd ${options.projectName}
 `;
+    const nextSteps = buildNextSteps(options);
     // Use the force luke! :)
     environment.outro(`${locationMessage}
 
 Use the following commands to start your app:
 ${cdInstruction}% ${formatCommand(getPackageManagerScriptCommand(options.packageManager, ['dev']))}
-
+${nextSteps}
 Please read the README.md file for information on testing, styling, adding routes, etc.${errorStatement}`);
 }
 export async function createApp(environment, options) {
@@ -281,6 +336,7 @@ export async function createApp(environment, options) {
     environment.startRun();
     await writeFiles(environment, effectiveOptions);
     await seedEnvValues(environment, effectiveOptions);
+    await writeEnvExample(environment, effectiveOptions);
     await runCommandsAndInstallDependencies(environment, effectiveOptions);
     environment.finishRun();
     report(environment, effectiveOptions);

package/dist/file-helpers.js

@@ -90,6 +90,20 @@ export function relativePath(from, to, stripExtension = false) {
 export function isDirectory(path) {
     return statSync(path).isDirectory();
 }
+export function isDemoFilePath(path) {
+    if (!path)
+        return false;
+    const normalized = path.replace(/\\/g, '/');
+    if (normalized.includes('/routes/demo/') ||
+        normalized.includes('/routes/example/')) {
+        return true;
+    }
+    const filename = normalized.split('/').pop() || '';
+    return (filename.startsWith('demo.') ||
+        filename.startsWith('demo-') ||
+        filename.startsWith('example.') ||
+        filename.startsWith('example-'));
+}
 export function findFilesRecursively(path, files) {
     const dirFiles = readdirSync(path);
     for (const file of dirFiles) {

package/dist/frameworks/react/add-ons/ai/info.json

@@ -1,6 +1,6 @@
 {
   "name": "AI",
-  "description": "TanStack AI integration and examples.",
+  "description": "Streaming chat UI with model-agnostic backend (OpenAI, Anthropic, etc).",
   "phase": "add-on",
   "modes": ["file-router"],
   "type": "add-on",

package/dist/frameworks/react/add-ons/better-auth/info.json

@@ -1,6 +1,6 @@
 {
   "name": "Better Auth",
-  "description": "Add Better Auth authentication to your application.",
+  "description": "Self-hosted user accounts and sessions (open source, full control).",
   "phase": "add-on",
   "type": "add-on",
   "category": "auth",

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

@@ -1,3 +1,44 @@
 ## Setting up Clerk
 
-- Set the `VITE_CLERK_PUBLISHABLE_KEY` in your `.env.local`.
+1. Sign up at [clerk.com](https://clerk.com) and create an application
+2. Copy the **Publishable Key** from the Clerk dashboard
+3. Set it in your `.env.local`:
+   ```bash
+   VITE_CLERK_PUBLISHABLE_KEY=pk_test_...
+   ```
+4. Visit the demo route at `/demo/clerk` once `npm run dev` is running
+
+### What's wired up
+
+- **`<ClerkProvider>`** at the app root (`src/integrations/clerk/provider.tsx`) handles auth context for the whole tree
+- **`<SignInButton>` / `<UserButton>`** in the header swap based on auth state
+- **`/demo/clerk`** shows Clerk's prebuilt sign-in UI and a signed-in greeting
+
+### Protecting a route
+
+Wrap any component in `<SignedIn>` / `<SignedOut>`:
+
+```tsx
+import { SignedIn, SignedOut, RedirectToSignIn } from '@clerk/clerk-react'
+
+function ProtectedPage() {
+  return (
+    <>
+      <SignedIn>
+        <YourPageContent />
+      </SignedIn>
+      <SignedOut>
+        <RedirectToSignIn />
+      </SignedOut>
+    </>
+  )
+}
+```
+
+For server-side checks (route loaders, server functions), see the Clerk docs on [`auth()`](https://clerk.com/docs/references/backend/auth).
+
+### Production checklist
+
+- Replace the test keys with **production keys** from a dedicated production Clerk instance
+- Configure your production domain under **Domains** in the Clerk dashboard
+- Set up social providers (Google, GitHub, etc.) under **User & Authentication → Social Connections**

package/dist/frameworks/react/add-ons/clerk/assets/src/routes/demo/clerk.tsx

@@ -1,20 +1,103 @@
 import { createFileRoute } from '@tanstack/react-router'
-import { useUser } from '@clerk/clerk-react'
+import {
+  SignIn,
+  SignedIn,
+  SignedOut,
+  useUser,
+} from '@clerk/clerk-react'
 
 export const Route = createFileRoute('/demo/clerk')({
-  component: App,
+  component: ClerkDemo,
 })
 
-function App() {
-  const { isSignedIn, user, isLoaded } = useUser()
+function ClerkDemo() {
+  return (
+    <div className="flex justify-center py-10 px-4">
+      <div className="w-full max-w-md p-6 space-y-6">
+        <SignedOut>
+          <div className="space-y-1.5">
+            <h1 className="text-lg font-semibold leading-none tracking-tight">
+              Sign in to continue
+            </h1>
+            <p className="text-sm text-neutral-500 dark:text-neutral-400">
+              Clerk renders the sign-in UI, manages sessions, and handles social providers for you.
+            </p>
+          </div>
+          <div className="flex justify-center pt-2">
+            <SignIn routing="hash" />
+          </div>
+          <p className="text-xs text-center text-neutral-400 dark:text-neutral-500">
+            Built with{' '}
+            <a
+              href="https://clerk.com"
+              target="_blank"
+              rel="noopener noreferrer"
+              className="font-medium hover:text-neutral-600 dark:hover:text-neutral-300"
+            >
+              CLERK
+            </a>
+            .
+          </p>
+        </SignedOut>
 
-  if (!isLoaded) {
-    return <div className="p-4">Loading...</div>
-  }
+        <SignedIn>
+          <SignedInGreeting />
+        </SignedIn>
+      </div>
+    </div>
+  )
+}
+
+function SignedInGreeting() {
+  const { user } = useUser()
+  if (!user) return null
+
+  const email = user.primaryEmailAddress?.emailAddress
+  const initial = (user.firstName || email || 'U').charAt(0).toUpperCase()
+
+  return (
+    <div className="space-y-6">
+      <div className="space-y-1.5">
+        <h1 className="text-lg font-semibold leading-none tracking-tight">
+          Welcome back
+        </h1>
+        <p className="text-sm text-neutral-500 dark:text-neutral-400">
+          You're signed in as {email}
+        </p>
+      </div>
 
-  if (!isSignedIn) {
-    return <div className="p-4">Sign in to view this page</div>
-  }
+      <div className="flex items-center gap-3">
+        {user.imageUrl ? (
+          <img src={user.imageUrl} alt="" className="h-10 w-10 rounded-full" />
+        ) : (
+          <div className="h-10 w-10 bg-neutral-200 dark:bg-neutral-800 flex items-center justify-center rounded-full">
+            <span className="text-sm font-medium text-neutral-600 dark:text-neutral-400">
+              {initial}
+            </span>
+          </div>
+        )}
+        <div className="flex-1 min-w-0">
+          <p className="text-sm font-medium truncate">
+            {user.firstName} {user.lastName}
+          </p>
+          <p className="text-xs text-neutral-500 dark:text-neutral-400 truncate">
+            {email}
+          </p>
+        </div>
+      </div>
 
-  return <div className="p-4">Hello {user.firstName}!</div>
+      <p className="text-xs text-center text-neutral-400 dark:text-neutral-500">
+        Manage your account from the avatar in the header. Built with{' '}
+        <a
+          href="https://clerk.com"
+          target="_blank"
+          rel="noopener noreferrer"
+          className="font-medium hover:text-neutral-600 dark:hover:text-neutral-300"
+        >
+          CLERK
+        </a>
+        .
+      </p>
+    </div>
+  )
 }

package/dist/frameworks/react/add-ons/clerk/info.json

@@ -1,6 +1,6 @@
 {
   "name": "Clerk",
-  "description": "Add Clerk authentication to your application.",
+  "description": "Hosted user accounts with prebuilt sign-in UI and social providers (managed).",
   "phase": "add-on",
   "modes": ["file-router"],
   "type": "add-on",

package/dist/frameworks/react/add-ons/compiler/info.json

@@ -1,7 +1,7 @@
 {
   "name": "Compiler",
   "phase": "setup",
-  "description": "Add React Compiler",
+  "description": "Auto-memoize components and hooks (fewer re-renders, no manual useMemo/useCallback).",
   "link": "https://react.dev/learn/react-compiler",
   "modes": ["code-router", "file-router"],
   "type": "add-on",

package/dist/frameworks/react/add-ons/convex/info.json

@@ -1,6 +1,6 @@
 {
   "name": "Convex",
-  "description": "Add the Convex database to your application.",
+  "description": "Reactive document database with real-time queries and serverless functions.",
   "link": "https://convex.dev",
   "phase": "add-on",
   "type": "add-on",

package/dist/frameworks/react/add-ons/drizzle/info.json

@@ -1,6 +1,6 @@
 {
   "name": "Drizzle",
-  "description": "Add Drizzle ORM to your application.",
+  "description": "Type-safe SQL query builder for Postgres, SQLite, or MySQL.",
   "phase": "add-on",
   "type": "add-on",
   "category": "orm",

package/dist/frameworks/react/add-ons/mcp/info.json

@@ -1,7 +1,7 @@
 {
   "name": "MCP",
   "phase": "setup",
-  "description": "Add Model Context Protocol (MCP) support.",
+  "description": "Expose your app as an MCP server so AI clients (Claude, Cursor) can call into it.",
   "link": "https://mcp.dev",
   "modes": ["file-router"],
   "type": "add-on",

package/dist/frameworks/react/add-ons/neon/info.json

@@ -1,6 +1,6 @@
 {
   "name": "Neon",
-  "description": "Add the Neon database to your application.",
+  "description": "Serverless Postgres (auto-scales to zero, branchable per environment).",
   "link": "https://neon.com",
   "phase": "add-on",
   "type": "add-on",

package/dist/frameworks/react/add-ons/paraglide/info.json

@@ -1,6 +1,6 @@
 {
   "name": "Paraglide (i18n)",
-  "description": "i18n with localized routing",
+  "description": "Type-safe i18n with localized routing and message bundles.",
   "phase": "add-on",
   "modes": ["file-router"],
   "type": "add-on",

package/dist/frameworks/react/add-ons/prisma/info.json

@@ -1,6 +1,6 @@
 {
   "name": "Prisma",
-  "description": "Add Prisma Postgres, or Prisma ORM with other DBs to your application.",
+  "description": "Type-safe database client with schema migrations (Postgres, MySQL, SQLite, MongoDB).",
   "phase": "add-on",
   "type": "add-on",
   "category": "orm",

package/dist/frameworks/react/add-ons/shadcn/info.json

@@ -1,6 +1,6 @@
 {
   "name": "Shadcn",
-  "description": "Add Shadcn UI to your application.",
+  "description": "Copy-paste accessible UI components (Tailwind + Radix primitives).",
   "phase": "add-on",
   "modes": ["file-router", "code-router"],
   "link": "https://ui.shadcn.com/",

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>
+  )
+}