BelgelerGeliştirici KılavuzuStrapi v5 Entegrasyonu ve Dinamik Alanlar

Strapi v5 CMS Entegrasyonu, Webhook'lar ve Terminalsiz Otomatik Senkronizasyon

Strapi v5 CMS sistemi; sayfa düzenleri, genel site ayarları, afişler, kaydırıcılar ve blog makalelerine ait verilerin depolanmasından sorumludur.

1. Next.js 16 Rotaları Neden Zorunlu Önbelleğe Alınır (Force-Cache)?

Next.js 16 App Router'da tüm fetch istekleri, milisaniyelik sayfa açılışları sağlamak için varsayılan olarak agresif şekilde önbelleğe alınır (Force-Cache). Strapi veya Medusa'da içerik güncellendiğinde önbelleği geçersiz kılmak ve temizlemek için İsteğe Bağlı Önbellek Yeniden Doğrulama (On-Demand Cache Revalidation) mimarisi kullanılır.

2. Strapi CMS Panelinde Webhook Yapılandırma Adım Adım Rehberi

Strapi'de bir sayfayı kaydetmenin veya yayınlamanın sunucuyu yeniden başlatmadan ön yüz önbelleğini anında temizlemesi için:

Strapi paneline giriş yapın ve Settings > Webhooks yolunu izleyin.
Create new Webhook butonuna tıklayın.
Name: Next.js Revalidation Webhook gibi açıklayıcı bir isim belirleyin.
URL: http://storefront:3000/api/revalidate (dahili Docker ağı) veya https://alanadiniz.com/api/revalidate adresini girin.
Events: Entry olaylarını (create, update, delete, publish ve unpublish) işaretleyin.

Güvenlik Başlığı (Header) ve Gizli Kod Yapılandırması

Strapi Webhook ayarlarındaki Headers bölümünde:

Name (Başlık Adı): Tam olarak x-strapi-secret ifadesini yazın.
Value (Başlık Değeri): .env dosyasındaki REVALIDATE_SECRET değişkeninin gizli anahtar değerini girin.
(Alternatif yöntem: Gizli anahtarı URL sonuna sorgu parametresi olarak ekleyin: ?secret=YOUR_REVALIDATE_SECRET).

İstek Özgünlüğü Doğrulaması: Özel x-strapi-secret başlığından veya sorgu parametresinden gizli kodun doğrulanması.
Seçici Önbellek Yönetimi: Strapi modeline karşılık gelen önbellek etiketlerinin (örn. strapi-homepage) temizlenmesi.

Gerekli Webhook'lar Kontrol Listesi

Sitenin ve önbelleğin kusursuz çalışması için Strapi'de aşağıdaki webhook'ları tanımlamalısınız. Hepsinde x-strapi-secret başlığı ayarlanmalıdır:

✔1. anasayfa: URL: /api/revalidate/home-page — Anasayfa ayarları değiştiğinde anasayfa önbelleğini temizler. Olaylar: Delete, Publish, Unpublish.
✔2. menü: URL: /api/revalidate/menu — Gezinme menüsü önbelleğini temizler. Önemli Not: Bu webhook için otomatik olay seçmenize gerek yoktur. Strapi Menü eklentisinde değişiklik yaptığınızda, değişiklikleri uygulamak için bu webhook üzerindeki Trigger butonuna manuel tıklamanız yeterlidir.
✔3. blog: URL: /api/revalidate/blog — Bir makale yayınlandığında veya düzenlendiğinde blog makaleleri ve liste önbelleğini günceller. Olaylar: Delete, Publish.
✔4. sayfalar: URL: /api/revalidate — Etiketlere göre önbellekleri temizlemek için diğer dinamik sayfa koleksiyonlarına yönelik genel webhook. Olaylar: Create, Update, Delete.
✔5. ayarlar (Genel Ayarlar & Sözlük): URL: /api/revalidate/strapi-settings — Genel mağaza ayarları (renkler, stiller) ve sözlük çevirileri için önbelleği anında temizler. Olaylar: Delete, Publish, Unpublish.

Next.js'de x-strapi-secret Güvenlik Doğrulaması Örneği (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. Veri Yapısı ve Dynamic Zones Bileşen Eşleştirmesi

Strapi'den çekilen blok dizisi, __component türü ve style varyantına göre Next.js React bileşenleriyle tip güvenli şekilde eşleştirilir.

4. MinIO S3 ile Görsel Optimizasyonu ve Medya Yönetimi

Strapi üzerinden yüklenen tüm görseller yerel MinIO S3 konteynerinde güvenle depolanır, otomatik WebP formatına dönüştürülür ve Caddy üzerinden hızlıca sunulur.

Mağaza Yönetimi Dağıtım API'si (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

Bu mimari, sunucu dosya sistemi ile yüklenen medyaları tamamen izole ederek yüksek güvenlik ve hız sağlar.

5. Üretim Ortamı İçin Kararlılık İpuçları

Strapi Önbellek Yönetimi İçin En İyi Pratikler

REVALIDATE_SECRET için her zaman güçlü ve rastgele bir anahtar kullanın. Taslak (Draft) durumundaki içeriklerin önbelleği erken temizlemesini önlemek için Webhook'u yalnızca yayınlama olaylarında tetikleyin.