Інтеграція 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}`],
  })
);

Серверний клієнт використовується в 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