Build & Ship a Stripe Storefront

Готовый магазин в действии — просмотрите категорию, откройте товар, добавьте в корзину и оформите заказ.

Пошаговое практическое руководство по созданию магазина, управляемого контентом, на Profound CMS: каталог товаров (категории + позиции), смоделированный в CMS, страницы списка и деталей из одного набора маршрутов и оформление заказа на стороне Stripe, поставленное в виде безголовного компонента.

Основой служат написанный вручную Next.js и админка Profound. Claude Code (через Profound MCP) выполняет основную работу в трёх задачах — наполнение каталога, подключение дизайн-системы и написание компонентов витрины (включая безголовую корзину). Три части: Настройка, Сборка, Продакшн.

Платёж в одну строку. Мы используем Stripe Checkout, размещённый на Stripe: покупатель платит на странице Stripe, а не на вашей. Ваше приложение выполняет всего две серверные задачи — создаёт сеанс Checkout и проверяет один вебхук. Никаких карточных полей, никаких Stripe Elements, никакой нагрузки PCI.

Что вы построите

• Небольшой опубликованный каталог в CMS — три категории и восемь товаров (демо «Изобретения Эдисона») — каждый можно редактировать торговцу без кода.
• Два параметрических маршрута (/products/{item_code}, /categories/{category_code}) плюс статический /cart, все из одного набора компонентов.
• Безголовую корзину (useCart) и Stripe Checkout, размещённый на Stripe, при этом цена всегда вычисляется на сервере по идентификатору Stripe Price.
• Магазин, развернутый на Vercel, с живым предпросмотром и редактированием на месте для команды.

Предварительные требования

• Bun ≥ 1.3 — curl -fsSL https://bun.sh/install | bash
• Claude Code с Profound MCP (устанавливается в части 1).
• Аккаунт Profound CMS.
• Учётная запись Stripe. В учебнике используется тестовый режим, поэтому при сборке не списываются реальные деньги — но поток идентичен с боевыми ключами, так что при желании используйте ключи реального аккаунта. (В тестовом режиме не нужны сведения о компании или банке.)
• Stripe CLI (stripe login) для локальных вебхуков.
• Для деплоя: GitHub CLI (gh) и аккаунт Vercel, подключённый к GitHub.

Как всё сочетается

Profound разделяет контент и рендеринг:

• Компоненты определяют форму контента. Пользовательский компонент с полем Route Slug доступен по маршруту (category, item); компонент, помеченный тегом UI Element, размещается на странице (nav, product_grid, ...).
• Документы — это контент (товар, категория).
• UI-элементы — секции страницы; каждое скалярное поле принимает статическое значение или CEL-выражение, вычисляемое при рендере.
• Параметрические маршруты сопоставляют URL с документом + UI-элементами, передавая параметры маршрута (meta.params.* в CEL, routeParams в React).
• Ваше приложение на Next.js читает данные через cms-renderer; Stripe добавляется как обычные API-маршруты.

Единственное правило, определяющее сборку: CEL привязывает только поля string/number. Поэтому скалярный «хром» (бренд в навигации, подвал, заголовки) привязан через CEL, а всё, что богаче или представляет коллекцию (сетку товаров, галерею изображений, rich-text), загружается внутри React-компонента по параметру маршрута. И Stripe — источник истины для цен: поле price в CMS используется только для отображения; списание всегда вычисляется на сервере по идентификатору Stripe Price.

Часть 1 — Настройка

Конечное состояние: небольшой опубликованный каталог, приложение подключено для чтения, Stripe установлен, дизайн на месте — пока ничего не отрисовывается.

1. Зарегистрируйтесь и создайте сайт

Зарегистрируйтесь в Profound (WorkOS). Создайте сайт с именем store, затем скопируйте его ID сайта (UUID в URL админки) и API-ключ уровня чтения (Deployments → Create API key). Приложение только читает; наполнение каталога позже идёт через MCP, который аутентифицируется отдельно.

2. Сгенерируйте каркас приложения, подключите его и добавьте Stripe

bunx create-profound-next store
cd store
bun add stripe

Каркас — это проект Next.js App Router, заранее подготовленный для Profound (cms-renderer SDK, маршрут-перехватчик, скрипт generate-schemas, <Refresher>). Стилизация не поставляется. bun add stripe подтягивает серверный SDK — единственную зависимость, необходимую для хостингового оформления заказа.

Добавьте ваши значения в .env.local:

# CMS
PROFOUND_API_KEY=<ваш ключ чтения>
NEXT_PUBLIC_PROFOUND_WEBSITE_ID=<ID вашего сайта>
NEXT_PUBLIC_CMS_API_URL=https://cms.dev.tryprofound.com
NEXT_PUBLIC_BUNNY_CDN_URL=https://cms-profound.b-cdn.net   # обслуживает изображения, размещённые в CMS

# Stripe
STRIPE_SECRET_KEY=sk_test_...            # здесь тестовый ключ; замените на боевой, когда выйдете в прод
STRIPE_WEBHOOK_SECRET=whsec_...          # будет заполнен на этапе сборки, шаг 4
NEXT_PUBLIC_SITE_URL=http://localhost:3000

Возьмите STRIPE_SECRET_KEY в Stripe → Developers → API keys. Мы используем тестовый ключ (sk_test_...), чтобы в процессе не проходили реальные платежи; переключитесь на боевой, когда будете готовы принимать настоящие. Запустите bun dev и откройте localhost:3000 — стартовый проект рендерится.

Хостинговое оформление заказа перенаправляет браузер на URL Stripe, поэтому серверного секретного ключа достаточно — ни публичного ключа, ни клиентского SDK Stripe не требуется.

3. Определите компоненты category, product_image и item

Создайте три пользовательских компонента (Components → Create new component) — это источник данных, поэтому без тега UI Element. Включите каждый (Active).

В CMS нет поля «массив изображений», поэтому галерея — это массив ссылок на компактный компонент product_image. Создайте category и product_image (и поставьте им Active) до item — поле-ссылка может указывать только на активные компоненты.

• category — name (Text), code (Text, Route Slug), description (Rich text), heroImage (Image)
• product_image — image (Image)
• item — name (Text), code (Text, Route Slug), description (Rich text), images (array of references → product_image), price (Number, в центах — только отображение), currency (Select, usd), stripePriceId (Text), category (Reference → category), active (Boolean)

Оставьте все поля необязательными. Админка переводит названия полей в нижний snake-case («Stripe Price Id» → stripe_price_id) — на них опирается ваш код, поэтому далее считывайте реальные имена из generate-schemas. Мы называем маршрутизируемое поле code (не slug): оно служит и Route Slug, и ключом для чистого запроса documents.getByCode позднее.

Компонент item — code как Route Slug, images как ссылки на product_image, плюс stripePriceId и ссылка category.

4. Скачайте компоненты в локальные типы

bun run generate-schemas

Команда записывает Zod-схемы и типы в generated/cms-schemas.ts (categorySchema/Category, itemSchema/Item). Заодно это проверка подключения — при неверных учётных данных команда завершится ошибкой.

5. Заполните каталог через Profound MCP

Установите и один раз аутентифицируйте MCP:

claude mcp add --transport http Profound http://107.21.107.99:8081/mcp

Выполните mcp__Profound__authenticate, пройдите поток WorkOS, затем попросите Claude:

Сгенерируй небольшой каталог для магазина «Изобретения Эдисона» — три категории и следующие товары с коротким описанием, соответствующим эпохе, price в центах, currency: "usd" и active: true:

• Освещение и энергия (code: lighting): Incandescent Lightbulb (incandescent-lightbulb, $24), Electric Dynamo (electric-dynamo, $890), Electric Pen (electric-pen, $49)
• Звукозапись (code: sound): Tinfoil Phonograph (tinfoil-phonograph, $249), Carbon Microphone (carbon-microphone, $59), Dictaphone (dictaphone, $179)
• Кинематограф (code: motion): Kinetoscope (kinetoscope, $399), Kinetograph Camera (kinetograph, $549)

Каждой категории нужны name и этот код в нижнем регистре; каждому товару нужны name, тот же код в нижнем регистре, description, price (в центах), currency и active. Сохрани в data/catalog.json и проверь на соответствие нашим компонентам category и item. Затем с помощью Profound MCP создай каждый документ как опубликованный: сначала категории, запиши их ID, затем создавай товары со ссылкой category вида { "_type": "reference", "_ref": "<category-id>", "_schema": "category" }. Товары создай параллельно.

Claude создаёт data/catalog.json, валидирует его и отправляет параллельные вызовы create_document (status: "published"). Наполняйте сначала категории, потом товары, чтобы ссылки указывали на уже существующие ID.

Три добавленные категории, опубликованы и Live.

Восемь добавленных товаров, каждый связан с категорией.

6. Создайте цены в Stripe и привяжите несколько товаров

Каталог находится в CMS; теперь дайте нескольким товарам реальную цену в Stripe — задача для торговца, выполняется в двух админках, без кода:

1. Stripe Dashboard → Products → + Add product, задайте единовременную цену, скопируйте Price ID (price_...).
2. Сделайте это для примерно трёх ключевых товаров (например, лампа, фонограф, кинетоскоп).
3. Админка Profound → item → Documents → вставьте идентификатор Price в stripePriceId, сохраните.

CMS хранит каталог; Stripe — источник истины для цены; связь — одна строка, которую торговец вставляет. (Хотите автоматизировать? Официальный Stripe MCP может создать Products/Prices за вас — вставьте полученные ID тем же способом.)

7. Подключите дизайн-систему и настройте её с помощью ИИ

Каркас поставляется без стилей. Поместите DESIGN.md (блок @theme Tailwind v4 + токены) в корень проекта — свой собственный или скачанный с refero.design. Затем дайте Claude запрос только про стили:

Прочитай дизайн-файл, который я только что добавил. Настрой Tailwind при необходимости, затем подключи тему и шрифты, чтобы стили заработали. Используй next/font для шрифтов — не загружай их из Google во время выполнения. Только стили — не создавай страницы или компоненты.

Убедитесь, что в src/app/globals.css есть @import "tailwindcss"; + блок @theme, и что localhost:3000 демонстрирует токены. Держите запрос чётким (если он открыт, агент может сгенерировать целую главную страницу) и загружайте шрифты через next/font, никогда — через импорт Google во время выполнения.

8. Добавьте изображения товаров (по желанию)

Необязательно — рабочее оформление заказа можно получить без изображений. Чтобы их добавить: создайте по документу product_image на каждое изображение (загрузите файл в поле image), затем свяжите их из массива images товара. Используйте собственные фотографии товаров или сгенерируйте согласованный набор при помощи модели изображений (попросите Claude вывести фирменные подсказки из DESIGN.md и зафиксировать один --sref в Midjourney, чтобы все снимки соответствовали стилю).

Отдельная библиотека cms-renderer не имеет помощника для URL изображений, поэтому добавьте функцию buildAssetUrl в src/lib/image.ts (~40 строк) — она добавит префикс NEXT_PUBLIC_BUNNY_CDN_URL и расширение. Компоненты из шага 3 части «Сборка» используют её.

Часть 2 — Сборка

Создайте слой отображения и оформление заказа, завершив всё реальной покупкой в тестовом режиме.

1. Определите пять компонентов UI-элементов

Пять компонентов, каждый Active и помечен тегом UI Element (Settings → Tags), без Route Slug:

• nav → brand
• product_grid → heading
• product_detail → heading
• cart_summary → heading
• footer → text

Все поля — Text. Тег UI Element делает компонент доступным в списке Add UI Element в Page Builder — одного признака Active недостаточно. Каждое поле является скаляром (тот тип, который можно привязать через CEL); собственно данные каталога не поле здесь — ProductGrid/ProductDetail извлекают их по параметру маршрута (шаг 3).

2. Перегенерируйте типы

bun run generate-schemas

3. Сгенерируйте читатель каталога, компоненты и безголовую корзину

Один запрос создаёт помощник чтения, пять компонентов, корзину и реестр:

Построй нашу витрину в src/, используя Profound SDK cms-renderer.

src/lib/catalog.ts — серверный читатель CMS. Создай клиент через getCmsClient({ cmsUrl: process.env.NEXT_PUBLIC_CMS_API_URL!, apiKey: process.env.PROFOUND_API_KEY, websiteId: process.env.NEXT_PUBLIC_PROFOUND_WEBSITE_ID! }) из cms-renderer/lib/cms-api. Экспортируй getItemByCode(code) → cms.documents.getByCode.query({ websiteId, schemaName: "item", code }), возвращая res.document.published_content. Экспортируй listItems(categoryCode?) → cms.documents.list.query({ websiteId, schemaName: "item", status: "published", limit: 100 }), сопоставь res.documents на .published_content, отфильтруй active !== false, и если задан categoryCode, оставь товары, у которых category._ref равен document.id категории. Экспортируй resolveImages(refs), который разрешает каждую ссылку item.images через cms.documents.get.query({ websiteId, id: ref._ref }) и превращает поле изображения в URL с помощью buildAssetUrl (Часть 1, шаг 8).

src/components/ — пять UI-компонентов, зарегистрированных в реестре маршрута-перехватчика по имени компонента, snake_case, чтобы совпадать с админкой: { nav, product_grid, product_detail, cart_summary, footer }. Nav и Footer читают свои скалярные поля из пропса content (тип BlockComponentProps<T> из cms-renderer/lib/types). ProductGrid и ProductDetail — асинхронные серверные компоненты, которые читают routeParams и получают данные через catalog.ts: routeParams.<param> — это { value, ... }, поэтому обращайся к .value, так что ProductGrid вызывает listItems(routeParams.category_code?.value) (карточки ссылаются на /products/{code}), а ProductDetail вызывает getItemByCode(routeParams.item_code?.value) (галерея через resolveImages, rich-text описание, цена, кнопка «Добавить в корзину»). CartSummary отображает корзину из useCart с кнопкой «Оплатить». Храни formatPrice в чистом файле src/lib/format.ts, чтобы клиентские компоненты не импортировали серверный catalog.ts.

src/components/AddToCartButton.tsx — компонент c директивой "use client", принимающий { code, name, priceLabel } и вызывающий useCart().addItem({ code, name, priceLabel, quantity: 1 }). Используй его внутри ProductDetail.

src/lib/useCart.ts — безголовая корзина: позиции { code, name, priceLabel, quantity } в состоянии, сохраняемые в localStorage, с методами addItem/removeItem/updateQty/subtotal и checkout(), который делает POST { lines: [{ code, quantity }] } (только коды и количества — никаких цен) на /api/stripe/checkout, затем перенаправляет на возвращённый url.

Стилизуй всё средствами нашей дизайн-системы, используя собственные компоненты — не копируй макет исходного сайта.

Три важных момента после выполнения:

• Скалярные данные интерфейса приходят через content ({ content }: BlockComponentProps<T>). Если деструктурировать поля как верхнеуровневые пропсы, блок ничего не отрисует. Данные каталога поступают из routeParams + запроса catalog.ts, потому что CEL не привязывает списки или галереи. Корзина несёт коды товаров, но не цены.
• routeParams.<param> — это { value, schemaName, document } — берите .value. Запросы возвращают published_content, а не .content. Ключи реестра — snake_case, чтобы совпадать с админкой.
• Обновите @types/react/@types/react-dom до v19 — каркас поставляется с v18, что ломает асинхронные серверные компоненты на React 19.

4. Напишите серверный код Stripe (основу)

Три коротких серверных файла — единственный платёжный код в приложении. Они переиспользуют getItemByCode, поэтому списание вычисляется на сервере.

src/lib/stripe.ts:

import Stripe from "stripe";
export const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);

src/app/api/stripe/checkout/route.ts — разрешает каждый товар из CMS, списывает цену Stripe:

import { NextResponse } from "next/server";
import { stripe } from "@/lib/stripe";
import { getItemByCode } from "@/lib/catalog"; // сервер, ключ только для чтения

export async function POST(req: Request) {
  const { lines } = await req.json();                // [{ code, quantity }] — от клиента без цен
  const line_items = await Promise.all(
    lines.map(async ({ code, quantity }: { code: string; quantity: number }) => {
      const item = await getItemByCode(code);          // сервер получает из CMS
      return { price: item!.stripe_price_id, quantity }; // цена из CMS, не с клиента
    })
  );
  const session = await stripe.checkout.sessions.create({
    mode: "payment",
    line_items,
    success_url: `${process.env.NEXT_PUBLIC_SITE_URL}/cart?status=success`,
    cancel_url: `${process.env.NEXT_PUBLIC_SITE_URL}/cart?status=cancelled`,
  });
  return NextResponse.json({ url: session.url });     // клиент перенаправляется сюда
}

src/app/api/stripe/webhook/route.ts — достоверный сигнал исполнения:

import { stripe } from "@/lib/stripe";

export async function POST(req: Request) {
  const body = await req.text();                      // сырой body — обязателен для проверки подписи
  const sig = req.headers.get("stripe-signature")!;
  let event;
  try {
    event = stripe.webhooks.constructEvent(body, sig, process.env.STRIPE_WEBHOOK_SECRET!);
  } catch {
    return new Response("Bad signature", { status: 400 });
  }
  if (event.type === "checkout.session.completed") {
    // выполнить заказ: записать заказ / отправить квитанцию
  }
  return new Response(null, { status: 200 });
}

Необходимое исправление каркаса: файл src/proxy.ts перенаправляет все /api/* в CMS, и ваши маршруты Stripe не выполняются. Пропускайте их первыми:

import { createCmsProxy } from "cms-renderer/lib/proxy";
import { NextResponse, type NextRequest } from "next/server";
import { cmsConfig } from "@/lib/cms-config";

const cmsProxy = createCmsProxy({ upstream: cmsConfig.cmsUrl });
const LOCAL_API_PREFIXES = ["/api/stripe"];

export const proxy = async (request: NextRequest) => {
  if (LOCAL_API_PREFIXES.some((p) => request.nextUrl.pathname.startsWith(p))) {
    return NextResponse.next();                       // обрабатываем локально
  }
  return cmsProxy(request as unknown as Parameters<typeof cmsProxy>[0]);
};
// оставьте неизменным каркасный `export const config = { matcher: [...] }`

Проверка: curl -X POST localhost:3000/api/stripe/webhook -d x возвращает Bad signature.

Запустите Stripe CLI для локальных вебхуков:

stripe login
stripe listen --forward-to localhost:3000/api/stripe/webhook
# вставьте whsec_... в STRIPE_WEBHOOK_SECRET, перезапустите bun dev

whsec_... действует только для текущей сессии. Безопасность обеспечивают два правила: checkout заново вычисляет цены по коду товара из CMS (поддельная корзина не может их поменять), а вебхук проверяет подпись по сырому телу запроса.

5. Создайте маршруты

Админка → Pages → Create page, три раза. Сопоставьте каждый параметр своему компоненту (поле slug — code):

1. /products/{item_code} → item
2. /categories/{category_code} → category
3. /cart — статическая страница (введите буквальный /cart, не /{cart})

6. Добавьте UI-элементы, настройте CEL, опубликуйте

Для каждого маршрута: Page Builder → Add UI Element → Custom → добавьте компоненты по порядку, заполните скалярные поля (статическое значение или CEL), Publish.

• /products/{item_code}: nav, product_detail, footer
• /categories/{category_code}: nav, product_grid, footer
• /cart: nav, cart_summary, footer

Задайте nav.brand и footer.text статическими строками; заголовкам — постоянные метки.

Page Builder на маршруте категории — выбран product_grid, его заголовок привязан через CEL.

Page Builder на маршруте товара — элемент product_detail, привязанный к конкретному товару.

Особенность параметрического Page Builder: на двух параметрических маршрутах добавленные UI-элементы не сохраняются (блоки остаются сиротами, и страница рендерится пустой). Пока это не исправлено, подключайте block_ids этих страниц напрямую через Profound MCP update_page, затем публикуйте. (Статический /cart прикрепляется штатно.) По той же причине ProductGrid берёт заголовок из найденной категории, а не через CEL.

7. Отрисовка и покупка

• /categories/lighting → сетка. Нажмите на товар → страница с деталями и кнопкой «Добавить в корзину». /cart → кнопка «Оплатить».
• Оплата перенаправляет к Stripe Checkout. Используйте тестовую карту 4242 4242 4242 4242, любую будущую дату и CVC. Вы вернётесь на /cart?status=success, а stripe listen покажет checkout.session.completed.

Страница товара — галерея, цена и кнопка «Добавить в корзину».

Корзина — позиции и одна кнопка «Оплатить через Stripe».

Оплатить можно только товары с прописанной ценой — выберите один из ~3, которые вы настроили на шаге 6.

Необязательно — интернационализируйте. Переведите каждый компонент (все 35 языков сразу), добавьте сегмент /{language}/..., сопоставленный со встроенным системным компонентом language, и переключите поля, привязанные через CEL, на documents.translated. См. урок про справочник аэропортов, часть 2, шаг 7.

Часть 3 — Продакшн

1. Запустите: GitHub, затем Vercel

git init && git add -A && git commit -m "Stripe storefront"
gh repo create store --private --source=. --push   # можно и --public

Команда сборки: generated/cms-schemas.ts добавлен в .gitignore, поэтому зафиксируйте сборку на повторной генерации — добавьте vercel.json:

{ "$schema": "https://openapi.vercel.sh/vercel.json", "buildCommand": "bun run generate-schemas && next build" }

В Vercel: Add New → Project, импортируйте store и добавьте переменные окружения — PROFOUND_API_KEY, NEXT_PUBLIC_PROFOUND_WEBSITE_ID, NEXT_PUBLIC_CMS_API_URL, NEXT_PUBLIC_BUNNY_CDN_URL, STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET (значение для прод-эндпоинта, см. ниже) и NEXT_PUBLIC_SITE_URL (ваш прод-URL). Разверните.

Затем подключите боевой вебхук (секрет локального stripe listen действовал только локально): Stripe → Developers → Webhooks → + Add endpoint → https://<prod>/api/stripe/webhook, событие checkout.session.completed. Вставьте его whsec_... в Vercel и переопубликуйте.

Отсутствующие переменные окружения = «работает локально, пусто в проде» — главный источник проблем при деплое. В учебнике мы выкатываемся с тестовыми ключами; переключите STRIPE_SECRET_KEY и секрет вебхука на боевые, когда будете готовы принимать реальные платежи.

2. Живой предпросмотр и редактирование на месте

Оба инструмента идут в комплекте с каркасом.

• Живой предпросмотр: <Refresher> обновляет страницу, которую просматривает редактор, когда в админке сохраняют изменения — без повторного деплоя. (Это предпросмотр для редактора; посетители видят опубликованный контент после обычной ревалидации.)
• Редактирование на месте: добавьте ?edit_mode=true к любому URL, чтобы показать оверлеи редактирования. Публичные посетители видят чистую страницу.

Добавьте маршрут предпросмотра, отсутствующий в каркасе. Админка загружает iframe предпросмотра по адресу /cms-preview_<path>; без этого маршрута каждый предпросмотр заканчивается 404. Добавьте его:

// src/app/cms-preview_/[...slug]/page.tsx
import { ParametricRoutePreviewPage } from "cms-renderer/lib/renderer";
import { registry } from "../../registry";   // вынесите реестр в общий модуль
export default async function Page({ params, searchParams }) {
  const { slug } = await params;
  const PreviewPage = ParametricRoutePreviewPage as any; // асинхронный RSC; типы React 19
  return <PreviewPage registry={registry} apiKey={process.env.PROFOUND_API_KEY ?? ""}
    websiteId={process.env.NEXT_PUBLIC_PROFOUND_WEBSITE_ID ?? ""}
    cmsUrl={process.env.NEXT_PUBLIC_CMS_API_URL ?? "https://cms.dev.tryprofound.com"}
    params={Promise.resolve({ slug })} searchParams={searchParams} />;
}

Добавьте также src/app/cms-preview_/page.tsx (аналогично, slug: []) для корня сегмента.

Вот и готово

Контент-ориентированная витрина Stripe: каталог в CMS, страницы списка и деталей из одного набора маршрутов и рабочее хостинговое оформление заказа. ИИ наполнил каталог, подключил дизайн и написал читатель каталога + компоненты + безголовую корзину; вы создали компоненты, связали цены Stripe, настроили три маршрута, привязали CEL-хром и добавили три коротких файла Stripe. CEL привязывает «хром»; компоненты получают каталог. А Stripe остался компактным — один вызов sessions.create и один подписанный вебхук, причём покупатель платит на собственном сайте Stripe.