Інтеграція 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 та прискорення виходу на ринок за рахунок готових рішень — реальні результати, які ми підтверджуємо метриками. Отримайте консультацію щодо вашого проєкту. Ми оцінимо обсяг робіт і запропонуємо оптимальне рішення.