Інтеграція 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 клієнти
| Характеристика | Server-side клієнт | Client-side клієнт |
|---|---|---|
| Тип автентифікації | Client Credentials (сервіс-2-сервіс) | Password Flow (токен користувача) |
| Область видимості | Весь каталог, ціни, inventory | Тільки дані поточного покупця |
| Кешування | ISR/SSG з revalidate | Немає (тільки React Query client) |
| Безпека | env-змінні, ніколи не потрапляє в браузер | Токен в httpOnly cookie |
| Продуктивність | Дуже високий TTFB (80-150 мс) | Залежить від мережі (200-400 мс) |
Як уникнути помилок інтеграції: типові проблеми та процес роботи
Конфлікт версій (409 ConcurrentModification)
Не передано актуальний `version`. Рішення: retry з отриманням свіжого об'єкта. Ми додаємо механізм автоматичної повторної спроби.400 InvalidInput на кошику
Triggered Extension відхилив операцію, читати `extensionExtraInfo`.Ціни не відображаються
Не передано `priceCurrency` та `priceChannel` в запиті.Slug не знайдено
Товар не опубліковано (`staged: true` замість `false`).Етапи та терміни
| Етап | Що робимо | Термін | Вартість (грн) |
|---|---|---|---|
| Аналітика | Аудит поточної архітектури, обсяг інтеграції, налаштування оточень commercetools | 2-3 дні | 12 000 |
| Проектування | Схема даних, типи товарів, таксономія, ендпоінти SDK | 3-5 днів | 20 000 |
| Реалізація | Налаштування клієнтів, ISR каталогу, кошик, автентифікація, пошук | 10-15 днів | 60 000 |
| Тест | Інтеграційні тести API, навантажувальне тестування (N+1, кеш) | 3-4 дні | 15 000 |
| Деплой | CI/CD, моніторинг, інвалідація кешу, документація | 2-3 дні | 10 000 |
| Загалом | 20-30 днів | 117 000 |
Що входить в роботу
- Документація: схема ендпоінтів, опис типів, приклади запитів.
- Доступи: client_id/secret для серверного клієнта, парольний флоу для покупців.
- Навчання: демонстрація роботи з SDK, пояснення типових помилок.
- Підтримка: 2 тижні після деплою — баг-фікси та консультації.
Чому обирають нас
- 5+ років досвіду з commercetools та платформами headless.
- 20+ успішних проєктів для e-commerce та B2B.
- Гарантія: Code Review перед кожним деплоєм, тести покриття >80%.
- Сертифікація: наші інженери пройшли офіційне навчання commercetools.
Зниження витрат на інфраструктуру на 30-50% завдяки ISR та прискорення виходу на ринок за рахунок готових рішень — реальні результати, які ми підтверджуємо метриками. Отримайте консультацію щодо вашого проєкту. Ми оцінимо обсяг робіт і запропонуємо оптимальне рішення.