# [Brand Name] · Hydrogen storefront

A headless Shopify storefront. Hydrogen handles Storefront API + cart; you handle design. Checkout stays on Shopify (PCI + Shop Pay).

## Source of truth
Shopify Admin is the source for products, collections, inventory, customers. Hydrogen reads via Storefront API. Cart state lives in a cookie. Orders flow through Shopify Checkout.

## Tech stack
Hydrogen 2025 + Remix v3 + React 19 + TypeScript. Tailwind v4 for styling. `@shopify/hydrogen` for the cart, search, customer account, and Storefront API client. Oxygen for hosting (Shopify's edge platform) OR Vercel.

## Deploy
- Local: `npm run dev` (Hydrogen dev server)
- Oxygen: `npx shopify hydrogen deploy --env=production`
- Vercel: `vercel deploy --prod` (requires the Vercel-compatible adapter)

## File map
- `app/root.tsx` root layout, Customer Account session
- `app/routes/_index.tsx` home
- `app/routes/products.$handle.tsx` PDP
- `app/routes/collections.$handle.tsx` PLP
- `app/routes/cart.tsx` cart drawer + page
- `app/routes/account.*.tsx` customer account routes (Hydrogen-provided)
- `app/components/` ProductCard, AddToCart, CartLineItem
- `app/lib/queries.ts` Storefront API GraphQL queries
- `app/lib/fragments.ts` shared GraphQL fragments
- `hydrogen.config.ts` storefront ID, API version

## .env keys
- `PUBLIC_STORE_DOMAIN` `your-store.myshopify.com`
- `PUBLIC_STOREFRONT_API_TOKEN` public Storefront API token
- `PRIVATE_STOREFRONT_API_TOKEN` private token (server-side queries with higher limits)
- `PUBLIC_CHECKOUT_DOMAIN` your `shop.yourbrand.com` if domain-mapped, else myshopify
- `PUBLIC_CUSTOMER_ACCOUNT_API_URL`
- `SESSION_SECRET` random 32-byte hex

## Hard rules
- All product data via Storefront API. Never hard-code prices, inventory, or availability.
- Cart state via Hydrogen's CartProvider. Don't reinvent cart logic.
- Image URLs through Shopify CDN with the `transform` query params (width, format=webp). Don't proxy through your own server.
- Checkout is Shopify's. Customers who try to "checkout in our app" want Shop Pay; let them.
- PDP must hit Lighthouse Performance 95+ on mobile. Hydrogen makes this achievable; default Shopify themes usually don't.
- Customer Account is OAuth-flowed via Shopify; do NOT roll your own auth.

## Recent significant changes
- 2026-04-30: Scaffolded. Locked: Hydrogen + Remix v3 (the Shopify-supported path), Oxygen for hosting (zero-config edge), Tailwind v4 over Polaris (Polaris is for the admin, not storefronts).

## Next session: start here
1. Create or pick a Shopify store. Issue Storefront API tokens (admin -> apps -> develop apps).
2. Map your domain or use the myshopify subdomain in dev.
3. Build the home + collection + PDP routes. Confirm the cart drawer works.
4. Test a real $1 order through Shopify Checkout end-to-end (Shop Pay too).
5. Run Lighthouse against PDPs. Hit 95+ mobile before launching.