Headless Commerce: Next.js Storefront Dev Guide

A headless commerce architecture separates concerns across three distinct layers: the frontend presentation layer, the commerce API layer, and the data layer. Each layer can evolve independently, allowing teams to upgrade or swap components without rebuilding the entire stack.

Our eCommerce solutions service covers full headless storefront development — from API integration through CDN deployment and ongoing performance monitoring.

The App Router (stable since Next.js 13.4, recommended for all new projects since Next.js 14) introduces React Server Components as the default rendering model. For commerce, this means product pages, collection listings, and search results render server-side with zero client JavaScript for the static content — only interactive elements like the cart button and product image carousel ship client code.

Recommended Project Structure

/app
├── (store)/
│   ├── layout.tsx          # Store layout (header, cart, footer)
│   ├── page.tsx            # Homepage (featured products, hero)
│   ├── products/
│   │   ├── page.tsx        # Product listing (SSG + search params)
│   │   └── [handle]/
│   │       └── page.tsx    # Product detail (SSG via generateStaticParams)
│   ├── collections/
│   │   └── [handle]/
│   │       └── page.tsx    # Collection pages (SSG)
│   └── cart/
│       └── page.tsx        # Cart review (dynamic, auth optional)
├── (checkout)/
│   └── checkout/
│       └── page.tsx        # Checkout (dynamic, client components)
└── api/
    ├── cart/route.ts       # Cart mutations (Server Actions preferred)
    └── revalidate/route.ts # ISR revalidation webhook endpoint

Rendering Strategy by Page Type

The Shopify Storefront API uses GraphQL, which allows you to request exactly the product fields you need — no over-fetching. Below are the essential queries for product pages and collection listings.

const PRODUCT_QUERY = `
  query ProductByHandle($handle: String!, $country: CountryCode)
  @inContext(country: $country) {
    product(handle: $handle) {
      id
      title
      description
      seo { title description }
      variants(first: 100) {
        nodes {
          id
          title
          availableForSale
          price { amount currencyCode }
          compareAtPrice { amount currencyCode }
          selectedOptions { name value }
        }
      }
      images(first: 10) {
        nodes { url altText width height }
      }
      metafields(identifiers: [
        { namespace: "custom", key: "size_guide" }
      ]) { value type }
    }
  }
`;

export async function generateStaticParams() {
  const products = await shopify.request(ALL_PRODUCT_HANDLES_QUERY, {
    variables: { first: 250 },
  });
  // Returns up to 250 products per request — paginate for larger catalogs
  return products.products.nodes.map((p) => ({ handle: p.handle }));
}

export const revalidate = false; // Static until revalidated by webhook

Cart state is the most complex client-side feature in a headless storefront. The cart must persist across page navigations, survive browser refresh, handle optimistic updates for instant feedback, and stay synchronized with the commerce backend's actual inventory and pricing.

Cart Architecture

Checkout Strategy

For Shopify-backed stores, redirect to Shopify's hosted checkout via the cart.checkoutUrl. This is the recommended approach — Shopify Checkout handles payment processing, tax calculation, shipping rate retrieval, discount codes, and order creation. Building a custom checkout is only warranted for Shopify Plus merchants who need custom checkout UI or non-Shopify payment processors.

Payment integration options depend on your commerce backend. For Shopify-backed stores, you have three options; for custom backends, direct Stripe integration is the standard approach.

For Stripe-specific implementation details — webhook handling, subscription billing, and error recovery — see our Stripe payment integration developer guide.

Performance is the primary business justification for headless commerce. These optimizations deliver the most measurable impact on Core Web Vitals and conversion rates.

Vercel is the optimal deployment platform for Next.js headless storefronts — it was built by the Next.js team and has first-class support for all App Router features including RSC, Server Actions, and ISR webhooks. Cloudflare Pages (via the OpenNext adapter) is a strong alternative for teams prioritizing edge latency globally.

Frequently Asked Questions