Next.js Önbelleği Nasıl Yenilenir? "On-Demand Cache Regeneration"

💡 Özet (TL;DR):

• Nedir: Incremental Static Regeneration (ISR) ile oluşturulan statik sayfaların önbelleğini, belirli bir zaman aşımı süresini (TTL) beklemeden, bir olay veya webhook tetiklemesiyle (on-demand) anında güncelleyen mekanizmadır.
• Pages Router (Klasik): pages/api/revalidate.js uç noktasında res.revalidate('/yol') metodu kullanılarak yapılır.
• App Router (Modern): Next.js 13+ ile gelen App Router'da Route Handler veya Server Action içinde revalidatePath('/yol') veya daha spesifik veriler için revalidateTag('etiket') fonksiyonları kullanılır.

Next.js, sitenizin derlenmesinden sonra da arka planda statik sayfalar oluşturmanıza veya güncellemenize olanak tanır. Incremental Static Regeneration (ISR) adı verilen bu özellik, sitenin tamamını baştan derlemenize gerek kalmadan sayfa bazında statik HTML üretilmesine izin verir.

Next.js 12.1 sürümü ile duyurulan On-demand Revalidation özelliği, headless WordPress yapısındaki bu siteyi oluştururken Nuxt.js yerine Next.js'i tercih etme sebebim olmuştu. Benzer özellik birkaç ay sonra Nuxt.js için de duyuruldu ve Nuxt.js (Vue) tekrar oyuna girdi.

Next.js v12.1.0 ile başlayarak On-Demand Incremental Static Regeneration özelliğini getirdi ve bu özellik spesifik bir sayfa için Next.js önbelleğini temizleme olanağı sağladı. Sonraki Next.js sürümü olan v12.2.0 ile bu özellik kararlı (stable) statüsü kazandı. Fakat unstable_revalidate() olan fonksiyon adını revalidate()'e çevirerek bu deneysel özelliği kullanan sitelerin hata vermesine neden oldu. Sonuç olarak web sitemin önbellek yenilemesinin hata verme nedenini çözmek bir saatime mal oldu.

Next.js Revalidation Yöntemleri Karşılaştırması

1. Klasik Yöntem: Pages Router (res.revalidate)

İlk olarak sadece Next.js uygulamanız tarafından bilinen bir gizli anahtar belirlemelisiniz. Bu anahtarı önbellek yenileme isteklerini alacak API uç noktanıza yetkisiz erişilmesini engellemek için kullanacaksınız. Aşağıdaki gibi bir URL yapısına sahip olacak bu uç noktayı manuel veya webhook yöntemi ile tetikleyebilirsiniz:

https://<alan-adiniz.com>/api/revalidate?secret=MY_SECRET_TOKEN

Belirlediğiniz bu gizli anahtarı ortam değişkenlerine ekleyin ve önbellek yenileme uç noktanızı aşağıdaki örneğe benzer şekilde oluşturun:

// pages/api/revalidate.js

export default async function handler(req, res) {
  // İsteğin geçerli olduğunu doğrulamak için gizli anahtarı kontrol edin.
  if (req.query.secret !== process.env.MY_SECRET_TOKEN) {
    return res.status(401).json({ message: 'Geçersiz anahtar' })
  }

  try {
    // Yol parametrik değil gerçek yol olmalıdır
    // Örneğin "/blog/[slug]" yerine "/blog/post-1" olmalıdır
    await res.revalidate('/path-to-revalidate')
    return res.json({ revalidated: true })
  } catch (err) {
    // Eğer önbellek yenilenirken bir hata olursa
    // Next.js oluşturulan son önbelleği kullanmaya devam edecektir
    return res.status(500).send('Önbellek temizleme başarısız oldu')
  }
}

2. Modern Yöntem: App Router (revalidatePath ve revalidateTag)

Next.js 13 ve sonrasındaki (Next.js 14, 15+) App Router mimarisinde önbellek yönetimi API Route'lar yerine Route Handlers veya Server Actions içinde gerçekleştirilir. Artık yol tabanlı veya veri etiketleme tabanlı (tag-based) yenileme yapabiliyoruz.

Örnek bir Route Handler (app/api/revalidate/route.js) üzerinden nasıl kullanıldığına bakalım:

// app/api/revalidate/route.js
import { revalidatePath, revalidateTag } from 'next/cache'

export async function POST(request) {
  const { searchParams } = new URL(request.url)
  const secret = searchParams.get('secret')
  const path = searchParams.get('path')
  const tag = searchParams.get('tag')

  // Güvenlik doğrulaması
  if (secret !== process.env.MY_SECRET_TOKEN) {
    return Response.json({ message: 'Geçersiz anahtar' }, { status: 401 })
  }

  try {
    if (path) {
      // Belirli bir yolu revalidate et (Örn: /blog/yazi-1)
      revalidatePath(path)
      return Response.json({ revalidated: true, path })
    }

    if (tag) {
      // Belirli bir veri etiketini revalidate et (Örn: 'posts')
      // Fetch yaparken { next: { tags: ['posts'] } } şeklinde etiketlenmiş istekleri etkiler
      revalidateTag(tag)
      return Response.json({ revalidated: true, tag })
    }

    return Response.json({ message: 'Eksik parametre (path veya tag belirtilmeli)' }, { status: 400 })
  } catch (err) {
    return Response.json({ message: 'Önbellek temizleme başarısız oldu' }, { status: 500 })
  }
}

Artık Next.js önbelleğini temizlemenizi sağlayacak bir API uç noktanız oldu. Bu uç noktayı tetikleme mantığınız arka uç (backend) tarafında çözülecektir. Örneğin ben headless WordPress yapımda yeni bir yazı/sayfa/kategori eklediğimde ya da güncellediğimde Next.js uç noktasını tetikleyen bir webhook kullanıyorum.

Daha fazla bilgi için Next.js Incremental Static Regeneration Dokümantasyonu (İngilizce) sayfasını inceleyebilirsiniz.

Bu Yazıda Yapılan Değişiklikler

• 11.05.2022: Yazı özeti düzenlendi.
• 21.06.2026: Türkçe imla ve terim kurallarına uygun olarak "ön bellek" kelimeleri "önbellek" olarak birleştirildi, Next.js marka ismi düzeltildi, modern Next.js App Router (revalidatePath ve revalidateTag) revalidation yöntemleri eklenerek kılavuz güncellendi.