Headless Commerce Integration with React/Next.js Storefront

Headless Commerce Integration with React/Next.js Storefront

Next.js is the standard choice for headless e-commerce storefront: SSG for SEO, ISR for data freshness, Server Components to reduce JS bundle, Edge Middleware for personalization. Integration with any Commerce API follows a single pattern.

Stack and dependencies

{
    "dependencies": {
        "next": "14.x",
        "react": "18.x",
        "@tanstack/react-query": "^5.0",
        "zustand": "^4.0",
        "graphql-request": "^6.0",
        "next-auth": "^4.0",
        "@vercel/analytics": "^1.0"
    },
    "devDependencies": {
        "@graphql-codegen/cli": "^5.0",
        "@graphql-codegen/typescript": "^4.0",
        "typescript": "^5.0"
    }
}

Commerce Client abstraction layer

Regardless of backend (Bagisto, Shopify, Medusa), create a unified interface:

// lib/commerce/types.ts
export interface Product {
    id: string;
    sku: string;
    slug: string;
    name: string;
    description: string;
    price: number;
    compareAtPrice?: number;
    images: ProductImage[];
    variants: ProductVariant[];
    categories: Category[];
}

export interface CommerceClient {
    getProduct(slug: string): Promise<Product>;
    getProducts(params: ProductsParams): Promise<PaginatedProducts>;
    getCategories(): Promise<Category[]>;
    createCart(): Promise<Cart>;
    addToCart(cartToken: string, item: CartItem): Promise<Cart>;
    checkout(cartToken: string, data: CheckoutData): Promise<Order>;
}

// lib/commerce/bagisto.ts
import { GraphQLClient } from 'graphql-request';
import type { CommerceClient, Product } from './types';
import { GET_PRODUCT, GET_PRODUCTS } from './queries';

export class BagistoClient implements CommerceClient {
    private client: GraphQLClient;

    constructor() {
        this->client = new GraphQLClient(
            process.env.NEXT_PUBLIC_BAGISTO_GRAPHQL_URL!,
            {
                headers: {
                    'Accept': 'application/json',
                },
            }
        );
    }

    async getProduct(slug: string): Promise<Product> {
        const { product } = await this.client.request(GET_PRODUCT, { slug });
        return this.normalizeProduct(product);
    }

    private normalizeProduct(raw: any): Product {
        return {
            id: String(raw.id),
            sku: raw.sku,
            slug: raw.urlKey,
            name: raw.name,
            description: raw.description,
            price: parseFloat(raw.priceHtml?.finalPrice ?? raw.price),
            images: raw.images?.map(img => ({
                url: img.path,
                altText: raw.name,
            })) ?? [],
            variants: raw.variants ?? [],
            categories: raw.categories ?? [],
        };
    }
}

Catalog pages with ISR

// app/products/[slug]/page.tsx (App Router)
import { commerce } from '@/lib/commerce';
import { ProductGallery } from '@/components/product/Gallery';
import { AddToCartButton } from '@/components/cart/AddToCartButton';
import { VariantSelector } from '@/components/product/VariantSelector';

interface Props {
    params: { slug: string };
}

export async function generateStaticParams() {
    const slugs = await commerce.getAllProductSlugs();
    return slugs.map(slug => ({ slug }));
}

export const revalidate = 3600;

export default async function ProductPage({ params }: Props) {
    const product = await commerce.getProduct(params.slug);

    return (
        <div className="grid grid-cols-1 lg:grid-cols-2 gap-12">
            <ProductGallery images={product.images} />
            <div>
                <h1 className="text-3xl font-bold">{product.name}</h1>
                <div className="mt-4 text-2xl">{product.price} ₽</div>
                <VariantSelector variants={product.variants} />
                <AddToCartButton productId={product.id} />
            </div>
        </div>
    );
}

// Metadata for SEO
export async function generateMetadata({ params }: Props) {
    const product = await commerce.getProduct(params.slug);
    return {
        title: product.name,
        description: product.description.slice(0, 160),
        openGraph: {
            images: [product.images[0]?.url],
        },
    };
}

Cart state management

Zustand for client-side cart state with persistence:

// stores/cart.ts
import { create } from 'zustand';
import { persist } from 'zustand/middleware';

interface CartState {
    cartToken: string | null;
    items: CartItem[];
    total: number;
    addItem: (productId: string, variantId?: string, qty?: number) => Promise<void>;
    removeItem: (lineId: string) => Promise<void>;
    clearCart: () => void;
}

export const useCartStore = create<CartState>()(
    persist(
        (set, get) => ({
            cartToken: null,
            items: [],
            total: 0,

            addItem: async (productId, variantId, qty = 1) => {
                let { cartToken } = get();

                if (!cartToken) {
                    const cart = await commerce.createCart();
                    cartToken = cart.token;
                    set({ cartToken });
                }

                const updatedCart = await commerce.addToCart(cartToken, {
                    productId,
                    variantId,
                    quantity: qty,
                });

                set({
                    items: updatedCart.items,
                    total: updatedCart.total,
                });
            },

            removeItem: async (lineId) => {
                const { cartToken } = get();
                if (!cartToken) return;

                const updatedCart = await commerce.removeFromCart(cartToken, lineId);
                set({ items: updatedCart.items, total: updatedCart.total });
            },

            clearCart: () => set({ cartToken: null, items: [], total: 0 }),
        }),
        { name: 'cart-storage', partialize: (state) => ({ cartToken: state.cartToken }) }
    )
);

Checkout flow

// app/checkout/page.tsx
'use client';

import { useForm } from 'react-hook-form';
import { zodResolver } from '@hookform/resolvers/zod';
import { checkoutSchema, CheckoutFormData } from '@/lib/validations/checkout';
import { useCartStore } from '@/stores/cart';

export default function CheckoutPage() {
    const { cartToken, clearCart } = useCartStore();
    const { register, handleSubmit, formState: { errors } } = useForm<CheckoutFormData>({
        resolver: zodResolver(checkoutSchema),
    });

    const onSubmit = async (data: CheckoutFormData) => {
        if (!cartToken) return;

        // Save address
        await commerce.saveShippingAddress(cartToken, data.shipping);

        // Get shipping methods
        const shippingMethods = await commerce.getShippingMethods(cartToken);

        // Select method and proceed to payment
        await commerce.saveShippingMethod(cartToken, shippingMethods[0].id);

        // Redirect to payment gateway
        const order = await commerce.placeOrder(cartToken, data.payment);
        clearCart();
        router.push(`/orders/${order.id}/success`);
    };

    return (
        <form onSubmit={handleSubmit(onSubmit)}>
            {/* form fields */}
        </form>
    );
}

Search with Algolia or Typesense

// components/search/SearchResults.tsx
import { InstantSearch, SearchBox, Hits, Configure } from 'react-instantsearch';
import { typesenseInstantsearchAdapter } from 'typesense-instantsearch-adapter';

const searchClient = new TypesenseInstantSearchAdapter({
    server: {
        apiKey: process.env.NEXT_PUBLIC_TYPESENSE_API_KEY!,
        nodes: [{ host: 'search.example.com', port: 443, protocol: 'https' }],
    },
    additionalSearchParameters: { query_by: 'name,sku,description' },
}).searchClient;

export function ProductSearch() {
    return (
        <InstantSearch searchClient={searchClient} indexName="products">
            <Configure hitsPerPage={24} />
            <SearchBox placeholder="Search products..." />
            <Hits hitComponent={ProductHit} />
        </InstantSearch>
    );
}

SEO: structured data

// components/product/ProductSchema.tsx
export function ProductSchema({ product }: { product: Product }) {
    const schema = {
        '@context': 'https://schema.org',
        '@type': 'Product',
        name: product.name,
        sku: product.sku,
        offers: {
            '@type': 'Offer',
            price: product.price,
            priceCurrency: 'RUB',
            availability: 'https://schema.org/InStock',
        },
        image: product.images.map(i => i.url),
    };

    return (
        <script
            type="application/ld+json"
            dangerouslySetInnerHTML={{ __html: JSON.stringify(schema) }}
        />
    );
}

Performance: Core Web Vitals

Storefront development timeline