Интеграция 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 решает проблему динамических цен
Если публиковать каталог полностью статически, цены устаревают. Мы используем Incremental Static Regeneration с revalidate: 300 для страниц товаров. Это даёт TTFB 80 мс и свежесть цен не более 5 минут. Для каталогов с частыми обновлениями — Redis-кэш поверх SDK с инвалидацией через webhook.
// 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 дня |
| Проектирование | Схема данных, типы товаров, таксономия, эндпоинты SDK | 3-5 дней |
| Реализация | Настройка клиентов, ISR каталога, корзина, аутентификация, поиск | 10-15 дней |
| Тест | Интеграционные тесты API, нагрузочное тестирование (N+1, кэш) | 3-4 дня |
| Деплой | CI/CD, мониторинг, инвалидация кэша, документация | 2-3 дня |
Что входит в работу
- Документация: схема эндпоинтов, описание типов, примеры запросов.
- Доступы: client_id/secret для серверного клиента, парольный флоу для покупателей.
- Обучение: демонстрация работы с SDK, объяснение типичных ошибок.
- Поддержка: 2 недели после деплоя — баг-фиксы и консультации.
Почему выбирают нас
- 5+ лет опыта с commercetools и платформами headless.
- 20+ успешных проектов для e-commerce и B2B.
- Гарантия: Code Review перед каждым деплоем, тесты покрытия >80%.
- Сертификация: наши инженеры прошли официальное обучение commercetools.
Снижение затрат на инфраструктуру на 30-50% благодаря ISR и ускорение вывода на рынок за счёт готовых решений — реальные результаты, которые мы подтверждаем метриками. Получите консультацию по вашему проекту. Мы оценим объём работ и предложим оптимальное решение.