ISR (Artımlı Statik Yenileme) Nedir?

Önce bayat sayfa, arkada yenisi

ISR'ın temel fikri HTTP dünyasındaki stale-while-revalidate davranışına benzer: süresi dolmuş içerik hemen sunulur, güncel sürüm arka planda hazırlanır. Next.js'te zamana bağlı bir ISR sayfasının yaşam döngüsü şöyledir:

1. Derleme sırasında sayfa üretilir ve önbelleğe alınır; gelen istekler bu kopyadan anında yanıtlanır.
2. Belirlenen süre (örneğin 60 saniye) dolduktan sonraki ilk istek yine eski sayfayı alır.
3. Aynı anda arka planda sayfanın yeni sürümü üretilmeye başlar.
4. Üretim başarılı olursa önbellekteki kopya değişir ve sonraki ziyaretçiler güncel sayfayı görür.
5. Üretim sırasında hata olursa son başarılı sürüm sunulmaya devam eder; bir sonraki istekte yeniden denenir.

Derleme sırasında hiç üretilmemiş bir adres istenirse sayfa o ilk istekte üretilip önbelleğe eklenir. Bu sayede yüz binlerce ürünlü bir katalogda yalnızca en çok ziyaret edilen sayfaları derleme anında üretmek, gerisini talep geldikçe oluşturmak mümkündür.

Next.js 16'da ISR'ı tanımlamanın yolları

Klasik App Router kullanımında süre, sayfa dosyasındaki revalidate dışa aktarımıyla, derleme anında üretilecek adresler ise generateStaticParams ile belirlenir:

// app/urunler/[slug]/page.tsx
export const revalidate = 3600; // en fazla saatte bir yenile

export async function generateStaticParams() {
  const urunler = await getPopulerUrunler();
  return urunler.map((u) => ({ slug: u.slug }));
}

cacheComponents ayarı açık projelerde aynı amaç farklı araçlarla karşılanır: önbelleğe alınacak fonksiyon veya bileşen 'use cache' yönergesiyle işaretlenir, ömrü cacheLife('days') gibi hazır profillerle belirlenir, veriler cacheTag ile etiketlenir. Next.js 16.3'ten itibaren bu modelde derlemeye dahil edilmemiş adreslere önce sayfanın URL'den bağımsız iskeleti (App Shell) sunulur, sayfa arka planda tamamlanır. Pages Router'da ise ISR, getStaticProps içindeki revalidate değeriyle çalışmaya devam eder; özellik ilk kez Next.js 9.5'te kararlı hâle gelmişti.

Süreye mi, olaya mı bağlı yenileme?

Zamana bağlı yenilemede içerik, süre dolana kadar bayat kalabilir. Next.js dokümantasyonu kısa süreler yerine yüksek bir değer (örneğin 1 saniye yerine 1 saat) seçip daha hassas ihtiyaçlar için talep üzerine yenileme kullanmayı önerir. Talep üzerine yenilemede bir Server Action veya Route Handler içinden revalidatePath('/blog') ya da etiket bazlı revalidateTag çağrılır. Tipik senaryo, CMS'te içerik yayımlandığında gönderilen bir webhook'un ilgili sayfayı geçersiz kılmasıdır. Kullanıcının kendi yaptığı değişikliği hemen görmesi gereken durumlar için Cache Components tarafında yalnızca Server Action'larda kullanılabilen updateTag vardır; bu fonksiyon bayat içerik sunmadan yeni veriyi bekler.

Kendi sunucunuzda çalıştırırken

• ISR, Node.js çalışma ortamı gerektirir; output: 'export' ile alınan statik çıktıda desteklenmez. Tamamen statik bir site için doğru kavram SSG'dir.
• Birden fazla sunucu örneği çalışıyorsa varsayılan dosya sistemi önbelleği her örneğe özeldir; talep üzerine yenileme yalnızca çağrıyı alan örneği günceller. Ortak bir cache handler yapılandırılmadıkça kullanıcılar örneğe göre farklı sürümler görebilir.
• Önde bir CDN varsa onun önbellek süresi de hesaba katılmalıdır; CDN sayfayı ISR süresinden daha uzun tutarsa yenilenen içerik kullanıcıya geç ulaşır. Next.js'in gönderdiği Cache-Control başlıkları bu yüzden kontrol edilmelidir.
• x-nextjs-cache yanıt başlığı HIT, STALE, MISS veya REVALIDATED değerleriyle sayfanın önbellekten mi geldiğini, arka planda mı yenilendiğini gösterir; sorun ayıklamada ilk bakılacak yerdir.

Güncel API ayrıntıları ve sınırlamalar Next.js ISR rehberinde yer alır. "ISR" adı Next.js'e özgüdür; başka araçlar benzer davranışı farklı adlarla veya doğrudan CDN katmanında sunar.