/library / template-shopify-hydrogen
templateWeb app

Shopify Hydrogen storefront (custom headless e-commerce)

A headless Shopify storefront on Hydrogen 2025 + Remix v3. Custom design, blazing-fast PDPs, Shop Pay still works. Use when Shopify themes can't express your brand and you want full design control without leaving the Shopify ecosystem.

use whenDTC brand outgrowing Shopify themes. You want custom design, control over performance, and your own deploy. Cart, checkout, and Shop Pay still go through Shopify.

April 30, 20262,130 bytesshopifyhydrogenremixecommerceheadless
download .md↓

[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.
← older
Discord bot with discord.js + slash commands
newer →
Chrome MV3 extension with TypeScript + Vite

Get the next CLAUDE.md in your inbox.

One new template every week, plus occasional case studies.