Next.js 16 ve App Router: Kendi Sunucunuzda Neler Kırılıyor?

Zihnindeki App Router modeli Next.js 14'ten kaldıysa üç şey artık yanlış. Turbopack hem next dev hem next build için varsayılan ve projede bir webpack yapılandırması varsa next build doğrudan başarısız oluyor. middleware dosyası proxy olarak yeniden adlandırıldı ve çalışma zamanı yalnızca Node.js. Üçüncüsü: senkron cookies(), headers(), params ve searchParams erişimi tamamen kaldırıldı.

Bu yazı, uygulamayı kendi sunucunuzda çalıştıranlar için 14'ten 16'ya giden yolda neyin kırıldığını anlatıyor. Doküman sürümü: 16.3.6.

Önce güvenlik: middleware'de yetkilendirme yapıyorsanız sürümünüzü bugün kontrol edin

CVE-2025-29927, CVSS 9.1 ile kritik seviyede ve doğrudan bu konuyla ilgili. x-middleware-subrequest başlığı kullanılarak middleware içindeki yetkilendirme kontrolleri atlatılabiliyor. Etkilenen aralıklar: 12.0.0-12.3.4, 13.0.0-13.5.8, 14.0.0-14.2.24 ve 15.0.0-15.2.2. Yamalı sürümler 12.3.5, 13.5.9, 14.2.25 ve 15.2.3.

Buradan çıkan mimari ders, yamadan daha kalıcı: yetkilendirmeyi tek katmanda yapmayın. Middleware (artık proxy) oturum çerezine bakıp yönlendirme yapsın; asıl yetki kontrolü veriye dokunan yerde, yani Server Component'te veya Server Action'ın ilk satırında tekrarlansın. Resmî doküman da Server Action'ları herkese açık HTTP uç noktası gibi ele almanızı söylüyor.

Kırılma sırası: Turbopack, proxy, async request API'leri

Turbopack. 16 ile varsayılan. webpack yapılandırmanız varsa next build yanlış yapılandırmayı engellemek için hata veriyor. Üç seçeneğiniz var: next build --turbopack ile webpack config'i yok saymak, yapılandırmayı Turbopack karşılıklarına taşımak, veya --webpack bayrağıyla eski derleyicide kalmak. Kendi webpack config'inizi yazmadığınız hâlde hata alıyorsanız sebep büyük ihtimalle bir eklenti.

middleware → proxy. Dosya adını (middleware.ts → proxy.ts) ve dışa aktarılan fonksiyon adını değiştiriyorsunuz. Kritik ayrıntı: proxy içinde edge çalışma zamanı desteklenmiyor; çalışma zamanı nodejs ve yapılandırılamıyor. Edge runtime'da kalmanız gerekiyorsa middleware'de kalmaya devam edeceksiniz.

Yapılandırma bayrakları da yeniden adlandırıldı: skipMiddlewareUrlNormalize artık skipProxyUrlNormalize. Sürüm 16 codemod'u bu bayrakları da güncelleyebiliyor.

Async request API'leri. 15'te geçici senkron uyumluluk vardı, 16'da tamamen kaldırıldı:

// Next.js 16
export default async function Page(props: PageProps<'/blog/[slug]'>) {
  const { slug } = await props.params
  const query = await props.searchParams
  return <h1>Blog: {slug}</h1>
}

Aynı kural opengraph-image, twitter-image, icon, apple-icon görsel üreticilerine ve sitemap'in id parametresine de uzandı; bunların hepsi artık Promise alıyor. Tip yardımcılarını npx next typegen ile üretebiliyorsunuz.

Cache API'si: revalidateTag artık tek argümanla çalışmıyor

16'da revalidateTag ikinci argüman olarak bir cacheLife profili istiyor; tek argümanlı kullanım kullanımdan kaldırıldı ve TypeScript hatası üretiyor.

// Önce
revalidateTag('posts')

// Sonra
revalidateTag('posts', 'max')

Yanına iki yeni API geldi. updateTag yalnızca Server Action'larda çalışıyor ve read-your-writes semantiği veriyor: kullanıcı kaydı değiştirdiğinde bayat veri yerine kendi değişikliğini hemen görüyor. refresh ise Server Action içinden istemci router'ını tazeliyor. Karar kuralı basit: blog yazısı, ürün kataloğu gibi gecikmesi tolere edilebilir içerikte revalidateTag; form ve kullanıcı ayarı gibi anında görünmesi gereken yerlerde updateTag.

Ayrıca experimental_ppr rota segmenti ve PPR bayrağı kaldırıldı; yerine cacheComponents geldi. Bu bir yeniden adlandırma değil: cacheComponents'i açmak, <Suspense> dışındaki önbelleklenmemiş veri için derleme hataları çıkarabiliyor.

Kendi sunucunuzda çalıştırıyorsanız Vercel rehberlerinin atladığı altı şey

KVKK, kurumsal politika veya maliyet nedeniyle uygulamayı kendi sunucunuzda çalıştırmak Türkiye'de yaygın. Resmî self-hosting rehberinin verdiği ayarlar, birden fazla kopya (container) çalıştırdığınız anda zorunlu hâle geliyor:

1. Paylaşılan önbellek. Varsayılan önbellek bellekte (50 MB) ve diskte tutuluyor; her pod kendi kopyasını taşıyor. cacheHandler ile kendi işleyicinizi verin ve cacheMaxMemorySize: 0 ile bellek içi önbelleği kapatın.
2. Etiket koordinasyonu. Bir kopyada çağrılan revalidateTag() yalnızca o kopyayı geçersiz kılıyor. Diğerleri bayat içerik sunmaya devam ediyor. Cache handler'ınızda refreshTags() metodunu uygulayın; her istekten önce çağrılıyor ve etiket durumunu paylaşılan depodan senkronlıyor.
3. Server Action şifreleme anahtarı. Her derleme kendi anahtarını üretiyor. Birden fazla kopya varsa hepsi aynı anahtarı kullanmalı, yoksa "Failed to find Server Action" hatası alıyorsunuz. NEXT_SERVER_ACTIONS_ENCRYPTION_KEY ile sabitleyin (base64, 16/24/32 bayt).
4. Sürüm kayması. Rolling deployment sırasında istemci eski derlemenin varlıklarını isteyebiliyor. deploymentId ayarlandığında statik varlıklara ?dpl=, gezinme isteklerine x-deployment-id ekleniyor ve uyuşmazlıkta tam sayfa yenileme tetikleniyor. Ayrıca generateBuildId ile git hash'ini kullanın.
5. nginx tamponlaması. Streaming ve Suspense kendi sunucunuzda destekleniyor ama proxy tamponlamayı kapatmanız gerekiyor. Rehberin verdiği yol X-Accel-Buffering: no başlığını eklemek. Yük dengeleyiciniz chunked transfer encoding veya HTTP/2 streaming desteklemiyorsa PPR'nin TTFB avantajı tamamen kayboluyor.
6. Düzgün kapanma. after() geri çağrılarının tamamlanması için sunucuya SIGINT veya SIGTERM gönderin ve bekleyin. Rehber 10-30 saniye drenaj süresi öneriyor. Orkestratörünüzde terminationGracePeriodSeconds bundan kısaysa arka plan işleriniz sessizce kesiliyor.

Ortam değişkenlerini derleme anında gömmek, tek Docker imajını ortamdan ortama taşımayı imkânsız kılıyor. Çalışma zamanında okumak için sunucu bileşeninde await connection() çağırın; bu dinamik render'a geçiriyor ve process.env gerçekten çalışma zamanında değerlendiriliyor. NEXT_PUBLIC_ önekli değişkenler ise derleme sırasında paketlenir, bu davranışın istisnası yok.

next/image varsayılanları sessizce değişti

Görüntü tarafındaki değişiklikler hata vermiyor ama çıktıyı değiştiriyor:

• minimumCacheTTL varsayılanı 60 saniyeden 4 saate (14.400 sn) çıktı.
• qualities varsayılanı artık yalnızca [75]. Listede olmayan bir quality değeri en yakın değere çekiliyor; yani quality={80} yazdıysanız 75 alıyorsunuz.
• imageSizes varsayılanından 16 çıkarıldı.
• maximumRedirects varsayılanı sınırsızdan 3'e indi.
• Yerel IP'lerin optimize edilmesi varsayılan olarak engellendi. Split-horizon DNS'li bir VPC içinde barındırıyorsanız 400 Bad Request alırsınız; dangerouslyAllowLocalIP yalnızca özel ağlar için ve SSRF riskini anladıktan sonra açılmalı.
• Sorgu dizesi taşıyan yerel görseller artık images.localPatterns.search yapılandırması istiyor.
• images.domains kullanımdan kaldırıldı; images.remotePatterns kullanın.

Tamamen kaldırılanlar

Bu üçü sessiz bozulma değil, derlemeyi durduran kaldırmalar: AMP desteği (next/amp, useAmp, amp yapılandırması), next lint komutu (ESLint veya Biome'u doğrudan çağırın; next build artık lint çalıştırmıyor) ve serverRuntimeConfig / publicRuntimeConfig. Paralel rotalarda her slot için default.js zorunlu hâle geldi; yoksa derleme başarısız oluyor. Minimum Node.js 20.9, minimum TypeScript 5.1.

Bu hafta yapılacak üç şey

Birincisi: package.json'daki Next.js sürümünüzü CVE-2025-29927 aralıklarıyla karşılaştırın. İkincisi: next.config.js dosyanızda webpack anahtarı var mı bakın; varsa 16 yükseltmesinin ilk işi bu. Üçüncüsü: birden fazla kopya çalıştırıyorsanız NEXT_SERVER_ACTIONS_ENCRYPTION_KEY ve deploymentId ayarlı mı kontrol edin; bu ikisi olmadan rolling deployment sırasında hata üretiyorsunuz ve log'da sebebi görünmüyor.

Konteyner ve dağıtım tarafı için Docker ile üretime dağıtım, mimari tarafı için mikroservis mi monolit mi, uç nokta güvenliği için API güvenliği yazılarına bakabilirsiniz. Next.js tarafındaki çalışma biçimimiz Next.js sayfasında; mevcut bir uygulamanın yükseltme kapsamı için iletişim sayfasından yazabilirsiniz.

Kırıcı değişiklikler ve yapılandırma anahtarları 25 Eylül 2026'da nextjs.org üzerindeki "How to upgrade to version 16" ve "How to self-host your Next.js application" rehberlerinden (doküman sürümü 16.3.6) doğrulanmıştır. Güvenlik açığı bilgileri GitHub Advisory GHSA-f82v-jwr5-mffw kaydındandır. Kod örnekleri resmî dokümandaki biçimi izler ve kendi ortamınıza uyarlanmadan üretime alınmamalıdır.