Shopify headless commerce: a technical implementation guide

Shopify's Hydrogen and Storefront API have matured significantly. We now recommend headless Shopify for any merchant doing over $2M annually or needing sub-second page loads.

Architecture overview

Our standard headless stack:

• Frontend: Next.js 15 App Router with React Server Components
• Commerce API: Shopify Storefront GraphQL API
• CMS: Sanity for editorial content
• Search: Algolia with merchandising rules
• Hosting: Vercel Edge Network
• Checkout: Shopify Checkout (native, not custom)

We never build custom checkout. Shopify's conversion-optimized checkout outperforms anything we could build.

Data flow

1. Next.js fetches product data via GraphQL at request time or build time
2. Editorial content comes from Sanity
3. User cart state is managed with Shopify Cart API
4. Checkout redirects to Shopify Checkout with cart token
5. Post-purchase, webhook syncs order data to our systems

Performance wins

Headless lets us optimize what Shopify monoliths cannot:

• Static generation: PDPs and PLPs pre-rendered at build time
• Edge caching: HTML cached at 100+ global PoPs
• Image optimization: Next.js Image component with AVIF
• Script reduction: No Shopify theme JavaScript
• Predictive prefetching: Links prefetched on hover

Average results across 8 migrations:

The tradeoffs

Headless is not universally better:

• Apps: Many Shopify apps require theme installation. We rebuild app functionality or use API equivalents.
• Complexity: You now maintain two systems (frontend + Shopify backend).
• Cost: Vercel + Algolia + Sanity adds ~$800/month vs Shopify's included hosting.
• Editor experience: Marketing teams need training on Sanity instead of Shopify theme editor.

Implementation tips

1. Use Shopify's generated types: @shopify/hydrogen-react exports TypeScript types from your schema
2. Cache aggressively: Product data changes rarely. Use 1-hour SWR for most queries.
3. Handle rate limits: Storefront API has rate limits. Implement request batching.
4. Test checkout flows: Cart metafields, discounts, and shipping must be validated end-to-end.
5. Plan for SEO: Redirect old URL structures. Implement structured data for products.

When to go headless

Go headless if you need:

• Sub-second page loads
• Custom editorial experiences
• Multi-region deployments
• Advanced A/B testing
• Custom integrations

Stay on Shopify themes if you are:

• Under $2M annual revenue
• Happy with theme customization
• Reliant on many Shopify apps
• Resource-constrained

We evaluate each client's needs individually. Headless is powerful but not always the right choice.