Сучасна інтеграція Headless Commerce з React/Next.js Storefront

Headless Commerce на Next.js: як прискорити вітрину і не переплачувати

Типова ситуація: ваш інтернет-магазин на монолітній CMS починає гальмувати при 1000 одночасних користувачів. TTFB зростає до 5 с, LCP — до 8 с. Ви вирішуєте перейти на Headless Commerce архітектуру, але стикаєтеся з проблемою інтеграції — кожен бекенд (Bagisto, Shopify, Medusa) вимагає свого формату даних. Джерело: Wikipedia Ми вирішуємо це за допомогою єдиного Commerce Client, який абстрагує відмінності та дозволяє швидко перемикати провайдера без переписування фронту.

У цій статті ми розглянемо, як створити React-вітрину (Next.js Storefront) для Headless Commerce, інтегрувати будь-який Commerce API, включаючи SSR e-commerce, ISR каталог, Next.js корзину. Розробка фронту e-commerce з використанням Headless CMS + Commerce та Next.js 14. Використовуємо Zustand корзину для управління станом. Команда має понад 7 років досвіду в e-commerce та реалізувала понад 30 успішних проєктів.

Наш досвід показує, що headless підхід з Next.js на 40–60% швидше завантажує сторінки порівняно з традиційним SSR на PHP, а згідно з Core Web Vitals від Google, LCP та CLS покращуються в середньому на 35%. В одному з проєктів ми знизили LCP з 4.2 с до 1.8 с, а INP — з 300 мс до 150 мс. При цьому економія на інфраструктурі досягає 40% за рахунок ISR та ефективного кешування. Середня вартість реалізації такого Storefront — від $18,000, а економія на інфраструктурі може сягати $5,000 на місяць.

Ми гарантуємо відповідність усім вимогам Core Web Vitals та надаємо сертифікат виконання.

Як інтегрувати будь-який Commerce API з Next.js?

Ключовий прийом — єдиний інтерфейс Commerce Client. Він абстрагує конкретний бекенд: чи то Bagisto, Shopify або Medusa, ми отримуємо однакові методи getProduct, getProducts, createCart і т.д. Це дозволяє змінювати провайдера без переписування всього фронту.

Такий підхід також спрощує тестування та підтримку: всі запити до бекенду проходять через один шар, де можна додати кешування, ретраї та логування.

// 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>;
}

Реалізація для Bagisto:

// 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 ?? [],
    };
  }
}

Чому варто обрати Next.js для headless e-commerce?

Next.js — стандартний вибір для headless e-commerce вітрини: SSG для SEO, ISR для актуальності даних, Server Components для зменшення JS-бандлу, Edge Middleware для персоналізації. Зв'язка з будь-яким Commerce API вибудовується за єдиним патерном.

Наш досвід показує, що ISR скорочує час завантаження сторінок каталогу в 2-3 рази порівняно з традиційним серверним рендерингом. А Server Components зменшують розмір клієнтського бандлу на 30–50% — це безпосередньо впливає на INP та взаємодію з користувачем. Додатково, preloading шрифтів та next/image додають скарбничку покращень.

Процес роботи над проєктом

1. Аналітика — вивчаємо ваш поточний бекенд, вимоги до каталогу, корзини, checkout. Визначаємо метрики: цільовий LCP < 2.5 с, CLS < 0.1, INP < 200 мс.
2. Проєктування — проєктуємо шар абстракції Commerce API, визначаємо контракти. Узгоджуємо інтерактивні прототипи.
3. Реалізація — пишемо компоненти на React/Next.js, налаштовуємо ISR, корзину, checkout. Використовуємо Zustand для клієнтського стану.
4. Тестування — перевіряємо метрики продуктивності, інтеграцію з бекендом. Проганяємо навантажувальне тестування до 2000 RPS.
5. Деплой — налаштовуємо CI/CD, деплоїмо на Vercel або ваш сервер. Надаємо повну документацію.

Сторінки каталогу з 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>
  );
}

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],
    },
  };
}

Управління станом корзини

Zustand для клієнтського стану корзини з персистентністю:

// 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-потік

// 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;
    await commerce.saveShippingAddress(cartToken, data.shipping);
    const shippingMethods = await commerce.getShippingMethods(cartToken);
    await commerce.saveShippingMethod(cartToken, shippingMethods[0].id);
    const order = await commerce.placeOrder(cartToken, data.payment);
    clearCart();
    router.push(`/orders/${order.id}/success`);
  };

  return (
    <form onSubmit={handleSubmit(onSubmit)}>
      {/* поля форми */}
    </form>
  );
}

Продуктивність: що впливає на Core Web Vitals

Що входить в роботу

• Шар абстракції Commerce API з документацією
• Вітрина на Next.js з ISR для каталогу
• Корзина на Zustand з персистентністю
• Checkout-форма з валідацією (Zod)
• Інтеграція пошуку (Algolia/Typesense) — опціонально
• Налаштування SEO: структуровані дані (JSON-LD), метадані, sitemap
• Деплой на хостинг (Vercel, AWS, Selectel) з CI/CD
• Документація, доступи, навчання команди замовника

Отримайте консультацію щодо інтеграції — ми допоможемо обрати архітектуру та оцінимо обсяг робіт.

Термін розробки вітрини

Замовте розробку вітрини під ключ — ми оцінимо ваш проект за 1 робочий день. Зв'яжіться з нами, щоб обговорити деталі та отримати консультацію.