Skip to content
Source
Sign inSign up
TanStack/cli

packages/create/src/frameworks/react/add-ons/shopify

Contents of packages/create/src/frameworks/react/add-ons/shopify
NameLast commit messageLast commit date
..
assets (directory)
info.json
package.json
README.md
small-logo.svg

README.md

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

RouteWhat it does
/shopShop landing — featured products + collections
/shop/products/$handleProduct detail (variants, images, options)
/shop/collections/$handleCollection grid with sort + pagination
/shop/cartCart line items, discount codes, checkout
/shop/searchProduct search
/shop/pages/$handleShopify CMS pages (about, etc.)
/shop/policies/$handlePrivacy, refund, terms, shipping

If you opted into customer accounts during scaffold:

RouteWhat it does
/shop/account/loginKick off Shopify OAuth
/shop/account/callbackOAuth callback handler
/shop/account/logoutEnd the customer session
/shop/accountDashboard
/shop/account/ordersOrder history
/shop/account/orders/$idOrder detail
/shop/account/addressesManage 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.