Интеграция commercetools с фронтендом

Интеграция commercetools с фронтендом

commercetools не имеет готового UI — только API. Фронтенд строится на любом стеке, но наиболее зрелая экосистема сложилась вокруг Next.js + @commercetools/platform-sdk. Альтернатива — Composable Commerce Frontend (бывший Frontastic), но она добавляет свой abstraction layer.

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. Клиентский (с токеном пользователя) — только в браузере.

Next.js: статическая генерация каталога

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

Для каталогов с частым обновлением цен — ISR с revalidate: 300.

Корзина: клиентский 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 Sync

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

Аутентификация покупателей

// app/api/auth/login/route.ts (Next.js Route Handler)
export async function POST(req: Request) {
  const { email, password } = await req.json();

  try {
    const customerClient = buildCustomerClient(email, password);
    const me = await customerClient.me().get().execute();

    const token = await getCustomerToken(email, password);

    const response = NextResponse.json({ customer: me.body });
    response.cookies.set("ct_token", token.access_token, {
      httpOnly: true,
      secure: true,
      maxAge: token.expires_in,
    });
    response.cookies.delete("cart_id"); // merging anonymous cart

    return response;
  } catch {
    return NextResponse.json({ error: "Invalid credentials" }, { status: 401 });
  }
}

Типичные ошибки интеграции

• 409 ConcurrentModification — не передан актуальный version. Решение: retry с получением свежего объекта
• 400 InvalidInput на корзине — triggered Extension отклонил операцию, читать extensionExtraInfo
• Цены не отображаются — не передан priceCurrency и priceChannel в запросе
• Slug не найден — товар не опубликован (staged: true вместо false)

Производительность и кэш

• RSC + fetch с next: { tags: ['products'] } → on-demand revalidation через webhook
• Для высоконагруженных каталогов — Redis кэш поверх SDK-запросов
• Изображения через commercetools CDN (cdn.commercetools.com) с трансформациями через query params