Loomix
ДокументацияРуководство РазработчикаИнтеграция со Strapi v5 и Dynamic Zones

Интеграция со Strapi v5 CMS, вебхуки и автосинхронизация без терминала

Система Strapi v5 CMS отвечает за хранение структуры страниц, глобальных настроек, баннеров, слайдеров и статей блога.

1. Почему маршруты Next.js 16 используют Force-Cache?

В App Router Next.js 16 все запросы fetch по умолчанию агрессивно кэшируются (Force-Cache) для открытия страниц за миллисекунды. При обновлении контента в Strapi или Medusa используется архитектура инвалидации кэша по требованию (On-Demand Revalidation) для мгновенной очистки кэша.

2. Пошаговая настройка вебхуков в Strapi CMS

Чтобы сохранение или публикация страницы в Strapi немедленно сбрасывали кэш фронтенда без перезапуска сервера:

  1. Войдите в панель управления Strapi и перейдите в Settings > Webhooks.
  2. Нажмите кнопку Create new Webhook.
  3. Name: Укажите понятное имя, например Next.js Revalidation Webhook.
  4. URL: Введите http://storefront:3000/api/revalidate (внутренняя сеть Docker) или https://yourdomain.com/api/revalidate.
  5. Events: Отметьте события в секции Entry (create, update, delete, publish и unpublish).
Настройка заголовков безопасности и секретного ключа
В секции Headers параметров вебхука в Strapi:
  • Name: Укажите точно x-strapi-secret.
  • Value: Введите секретное значение переменной REVALIDATE_SECRET из вашего файла .env.
  • (Альтернатива: укажите секретный ключ как query-параметр в URL: ?secret=YOUR_REVALIDATE_SECRET).
  • Проверка подлинности: Валидация секретного ключа из заголовка x-strapi-secret или query-параметра.
  • Выборочная инвалидация кэша: Очистка тегов кэша, соответствующих модели Strapi (напр., strapi-homepage).

Чек-лист обязательных вебхуков

Для оптимальной работы настройте в Strapi следующие вебхуки, каждый с заголовком x-strapi-secret:

  • ✔1. Главная страница (home-page): URL: /api/revalidate/home-page — Сброс кэша главной страницы при изменении настроек. События: Delete, Publish, Unpublish.
  • ✔2. Меню (menu): URL: /api/revalidate/menu — Сброс кэша навигационного меню. Примечание: Не требует автоматических событий; при изменении меню нажмите кнопку Trigger для применения.
  • ✔3. Блог (blog): URL: /api/revalidate/blog — Обновление списка и статей блога при редактировании или публикации. События: Delete, Publish.
  • ✔4. Страницы (pages): URL: /api/revalidate — Универсальный вебхук для других динамических коллекций по их тегам. События: Create, Update, Delete.
  • ✔5. Глобальные настройки и словарь: URL: /api/revalidate/strapi-settings — Мгновенный сброс для глобальных настроек (цвета, стили) и переводов. События: Delete, Publish, Unpublish.
Пример проверки безопасности в Next.js (app/api/revalidate/route.ts)
typescript
import crypto from "node:crypto"
import { revalidateTag } from "next/cache"
import { NextRequest, NextResponse } from "next/server"
 
function isValidSecret(providedSecret: string | null): boolean {
  if (!providedSecret || !process.env.REVALIDATE_SECRET) return false
  const actual = new Uint8Array(crypto.createHash("sha256").update(providedSecret).digest())
  const expected = new Uint8Array(crypto.createHash("sha256").update(process.env.REVALIDATE_SECRET).digest())
  return crypto.timingSafeEqual(actual, expected)
}
 
export async function POST(request: NextRequest) {
  const secret = request.headers.get("x-strapi-secret") || request.nextUrl.searchParams.get("secret")
 
  if (!isValidSecret(secret)) {
    return NextResponse.json({ message: "Invalid secret" }, { status: 401 })
  }
 
  const body = await request.json()
  
  if (body.model) {
    revalidateTag(`strapi-${body.model}`)
  }
 
  return NextResponse.json({ revalidated: true, now: Date.now() })
}

3. Структура данных и маппинг Dynamic Zones

Массив блоков из Strapi строго типизировано сопоставляется с компонентами React на основе типа __component и варианта style.

4. Оптимизация изображений и хранилище MinIO S3

Все изображения, загружаемые в Strapi, сохраняются в локальном контейнере MinIO S3, автоматически конвертируются в формат WebP и молниеносно отдаются через Caddy.

API Диспетчеризации для Управления Витриной (Dispatch API)
bash
# Trigger component style sync via Strapi Admin API:
POST /api/storefront/sync-component
{
  "componentName": "home/components/ProductShowcase",
  "style": "style-2",
  "action": "add",
  "autoDeploy": false
}
 
# Trigger batch production build to GitHub Actions:
POST /api/storefront/build

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

5. Рекомендации по стабильности для продакшена

Лучшие практики управления кэшем в Strapi
Всегда используйте надежный случайный ключ для REVALIDATE_SECRET. Чтобы избежать преждевременного сброса кэша при редактировании черновиков (Draft), включайте вебхук только на события публикации.