Інтеграція commercetools з фронтендом: архітектура та практика

Інтеграція commercetools з фронтендом: архітектура та практика

commercetools не має готового UI — тільки API. Це означає, фронтенд доводиться будувати з нуля, і вибір стека безпосередньо впливає на продуктивність та вартість підтримки. Найзріліша екосистема склалася навколо Next.js з @commercetools/platform-sdk. За 5 років ми реалізували понад 20 headless-проєктів — від інтернет-магазинів до B2B-порталів — і набили шишки, які вам не доведеться повторювати. Типові болі: помилка ConcurrentModification при роботі з кошиком, втрачені ціни через неправильний priceCurrency, гальмуючий пошук без кешування. Щоб не наступати на ці граблі, розберемо ключові архітектурні рішення і покажемо, як ISR дає TTFB у 5 разів швидший за традиційний SSR, а синхронізація через Subscriptions оновлює пошук за секунди замість годин.

Чому headless commercetools — це виклик для фронтенду?

На відміну від монолітних CMS, commercetools не надає ні рендерингу, ні кешування. Всю логіку представлення бере на себе фронтенд. Це дає свободу, але вимагає грамотної архітектури: розділення клієнтів (серверний та клієнтський), інкрементальна статика, обробка конфліктів версій. Непідготовлена команда часто отримує N+1 запити, високий TTFB та втрату даних кошика.

SDK та ініціалізація клієнта

npm install @commercetools/platform-sdk @commercetools/sdk-client-v2 \
 @commercetools/sdk-middleware-auth @commercetools/sdk-middleware-http \
 @commercetools/sdk-middleware-queue

Три клієнти для трьох контекстів:

// lib/ctpClient.ts
import { createClient } from "@commercetools/sdk-client-v2";
import { createApiBuilderFromCtpClient } from "@commercetools/platform-sdk";

function buildClient(authMiddleware: Middleware) {
  return createApiBuilderFromCtpClient(
    createClient({
      middlewares: [
        authMiddleware,
        createQueueMiddleware({ concurrency: 5 }),
        createHttpMiddleware({
          host: `https://api.${process.env.CTP_REGION}.commercetools.com`,
        }),
      ],
    })
  ).withProjectKey({ projectKey: process.env.CTP_PROJECT_KEY! });
}

export const serverApiRoot = buildClient(
  createAuthMiddlewareForClientCredentialsFlow({
    host: `https://auth.${process.env.CTP_REGION}.commercetools.com`,
    projectKey: process.env.CTP_PROJECT_KEY!,
    credentials: {
      clientId: process.env.CTP_SERVER_CLIENT_ID!,
      clientSecret: process.env.CTP_SERVER_CLIENT_SECRET!,
    },
    scopes: [`view_products:${process.env.CTP_PROJECT_KEY}`],
  })
);

Server-side клієнт використовується в getStaticProps / RSC. Клієнтський (з токеном користувача) — тільки в браузері.

Як ISR прискорює каталог у 5 разів?

Якщо публікувати каталог повністю статично, ціни застарівають. Ми використовуємо Incremental Static Regeneration з revalidate: 300 для сторінок товарів. Це дає TTFB 80 мс і свіжість цін не більше 5 хвилин. Для каталогів з частими оновленнями — Redis-кеш поверх SDK з інвалідацією через webhook. Порівняно з традиційним SSR, ISR знижує витрати на інфраструктуру на 30-50% та прискорює завантаження в 5 разів (За даними тестування продуктивності на 10 000 запитів).

// app/catalog/[slug]/page.tsx (App Router)
import { serverApiRoot } from "@/lib/ctpClient";

export async function generateStaticParams() {
  const products = await serverApiRoot
    .productProjections()
    .get({
      queryArgs: {
        limit: 500,
        staged: false,
        where: 'masterData(published = true)',
      },
    })
    .execute();
  return products.body.results.map((p) => ({
    slug: p.slug["ru"],
  }));
}

export default async function ProductPage({
  params,
}: {
  params: { slug: string };
}) {
  const result = await serverApiRoot
    .productProjections()
    .get({
      queryArgs: {
        where: `slug(ru = "${params.slug}")`,
        expand: ["productType", "categories[*]"],
        priceCurrency: "RUB",
        priceChannel: "channel-key=storefront-ru",
      },
    })
    .execute();
  const product = result.body.results[0];
  if (!product) notFound();
  return <ProductDetail product={product} />;
}

Як організувати кошик: клієнтський state + API

Кошик зберігається в commercetools — cartId зберігається в cookie. Жодного дублювання в localStorage.

// hooks/useCart.ts
import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
import { browserApiRoot } from "@/lib/ctpClientBrowser";
import Cookies from "js-cookie";

export function useCart() {
  const queryClient = useQueryClient();
  const cartId = Cookies.get("cart_id");

  const { data: cart } = useQuery({
    queryKey: ["cart", cartId],
    queryFn: async () => {
      if (!cartId) return null;
      return (await browserApiRoot.carts().withId({ ID: cartId }).get().execute()).body;
    },
    enabled: !!cartId,
  });

  const addToCart = useMutation({
    mutationFn: async ({
      productId,
      variantId,
      quantity,
    }: {
      productId: string;
      variantId: number;
      quantity: number;
    }) => {
      if (!cartId) {
        const newCart = await browserApiRoot.carts().post({
          body: {
            currency: "RUB",
            store: { typeId: "store", key: "web-ru" },
            lineItems: [{ productId, variantId, quantity }],
          },
        }).execute();
        Cookies.set("cart_id", newCart.body.id, { expires: 30 });
        return newCart.body;
      }
      return (await browserApiRoot.carts().withId({ ID: cartId }).post({
        body: {
          version: cart!.version,
          actions: [{ action: "addLineItem", productId, variantId, quantity }],
        },
      }).execute()).body;
    },
    onSuccess: (updatedCart) => {
      queryClient.setQueryData(["cart", updatedCart.id], updatedCart);
    },
  });

  return { cart, addToCart };
}

Як синхронізувати пошук з Algolia?

Commercetools не надає повнотекстовий пошук з релевантністю рівня Algolia. Продуктивне рішення — синхронізація через Subscriptions:

// subscriptions/algolia-sync.ts
// Commercetools Subscription → SQS → Lambda → Algolia
export async function handler(event: SQSEvent) {
  for (const record of event.Records) {
    const message = JSON.parse(record.body);
    const { notificationType, resourceTypeId, resourceUserProvidedIdentifiers } = message;
    if (resourceTypeId !== "product") continue;
    const product = await serverApiRoot
      .products()
      .withId({ ID: message.resource.id })
      .get({ queryArgs: { expand: ["productType"] } })
      .execute();
    if (notificationType === "ResourceDeleted") {
      await algoliaIndex.deleteObject(message.resource.id);
    } else {
      await algoliaIndex.saveObject(transformForAlgolia(product.body));
    }
  }
}

Автентифікація покупців та об'єднання кошиків

Для логіну використовуємо Customer SDK. Після успішної автентифікації об'єднуємо анонімний кошик з кошиком користувача — це стандарт для commercetools. Деталі реалізації в Next.js Route Handlers з httpOnly cookies.

Server-side vs Client-side клієнти

Як уникнути помилок інтеграції: типові проблеми та процес роботи

Етапи та терміни

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

• Документація: схема ендпоінтів, опис типів, приклади запитів.
• Доступи: client_id/secret для серверного клієнта, парольний флоу для покупців.
• Навчання: демонстрація роботи з SDK, пояснення типових помилок.
• Підтримка: 2 тижні після деплою — баг-фікси та консультації.

Чому обирають нас

• 5+ років досвіду з commercetools та платформами headless.
• 20+ успішних проєктів для e-commerce та B2B.
• Гарантія: Code Review перед кожним деплоєм, тести покриття >80%.
• Сертифікація: наші інженери пройшли офіційне навчання commercetools.

Зниження витрат на інфраструктуру на 30-50% завдяки ISR та прискорення виходу на ринок за рахунок готових рішень — реальні результати, які ми підтверджуємо метриками. Отримайте консультацію щодо вашого проєкту. Ми оцінимо обсяг робіт і запропонуємо оптимальне рішення.