یکپارچه‌سازی Strapi v5 CMS، وب‌هوک‌ها و همگام‌سازی اتوماتیک بدون ترمینال

۱. چرا روت‌های Next.js 16 فورس‌کش (Force-Cache) می‌شوند؟

در Next.js 16 App Router، تمامی درخواست‌های fetch به‌طور پیش‌فرض به صورت سرسختانه کش می‌شوند (Force-Cache) تا لود صفحات میلی‌ثانیه‌ای شود. جهت بازنشانی و پاکسازی کش هنگام بروزرسانی محتوا در Strapi یا Medusa، از معماری On-Demand Cache Revalidation استفاده شده است.

۲. راهنمای گام‌به‌گام تنظیم Webhook در پنل Strapi CMS

برای این‌که با ذخیره یا انتشار برگه در Strapi، کش فرانت‌اند فوراً و بدون ری‌استارت سرور پاک شود:

1. وارد پنل Strapi شوید و به مسیر Settings > Webhooks بروید.
2. دکمه Create new Webhook را بزنید.
3. Name: نام دلخواه مانند Next.js Revalidation Webhook بگذارید.
4. URL: آدرس http://storefront:3000/api/revalidate (در شبکه داخلی داکر) یا https://yourdomain.com/api/revalidate را وارد کنید.
5. Events: تیک رویدادهای Entry (ایجاد، ویرایش، حذف، انتشار و لغو انتشار) را بزنید.

• تایید اصالت درخواست: دریافت سکرت از هدر اختصاصی x-strapi-secret یا پارامتر کوئری.
• مدیریت کش انتخابی: پاکسازی کش برچسب‌های متناظر با مدل استرپی (مثلاً strapi-homepage).

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

۳. Revalidate اتوماتیک کش محصولات از سمت Medusa

هنگامی که محصولی در پنل Medusa ویرایش می‌شود، Subscriber یا Workflow مربوطه رویداد product.updated را پردازش کرده و یک در خواست HTTP به `/api/revalidate` ارسال می‌کند تا برچسب‌های کش products و product-[id] منقضی گردند.

۴. مدیریت استورفرانت و همگام‌سازی استایل‌ها در Strapi

استراپی دارای یک صفحه اختصاصی Storefront Management ساخته شده با Strapi Design System است. از این صفحه، مدیران محتوا و برنامه‌نویسان می‌توانند کامپوننت مورد نظر را انتخاب کرده، استایل جدید را وارد نمایند، صف تغییرات را بررسی کنند و با یک کلیک بیلد پروداکشن را از طریق GitHub Actions بدون نیاز به SSH یا دسترسی مستقیم به سرور تریگر کنند.

# 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

تغییرات در فایل .sync-history.json ذخیره می‌شوند تا بتوان چندین کامپوننت را به‌صورت دسته‌ای قبل از ارسال بیلد نهایی تنظیم کرد.