Altı route rule, Nuxt 4.5 SSR streaming'i sessizce devre dışı bırakıyor

Dev.to'da yayınlanan bir yazı, Nuxt 4.5'ün deneysel server-side rendering streaming özelliğindeki bir tuzağı ele alıyor: global bayrağı açmak her route'u değiştirmiyor, çünkü altı specific route rule bu route'ları sessizce eski buffer'lı renderer'a geri döndürüyor — ve streaming başladıktan sonra response'a yazan uygulama kodu production'da ERR_HTTP_HEADERS_SENT hatasıyla başarısız oluyor.

Yazıya göre özellik 18 Temmuz 2026'da Nuxt 4.5.0 ile geldi, hâlâ opt-in ve açıkça deneysel, ve npm'in latest tag'indeki 4.5.2 sürümüne karşı doğrulandı. Yazarın 31 Temmuz 2026'da end-of-life'a ulaştığını söylediği Nuxt 3 bu özelliği hiç almıyor.

Streaming response'u nasıl değiştiriyor

Buffer'lı SSR altında — şimdiye kadar Nuxt uygulamalarında varsayılan davranış — sunucu sayfanın tamamını bellekte bir string olarak render ediyor, ancak sonrasında final status kodunu, header'ları ve cookie'leri belirleyip tek bir tam response gönderiyor. Streaming bu sırayı tersine çeviriyor. Nuxt önce dış kabuğu render ediyor — root layout, head, ilk asenkron boundary'e kadar her şeyi — ve o parça hazır olduğu anda status ve header'ları socket'e işliyor. Ardından diğer component'ler render olmaya devam ederken kalan body'yi aynı açık bağlantıya eklemeye devam ediyor.

Bu erken flush, yazının öne çıkardığı ana kazanımdı: Time to First Byte'nin basit bir sayfada 1,8 saniyeden 40 milisaniyeye düşmesi, çünkü tarayıcı baytları alıyor, sunucu hâlâ çalışırken boyamaya başlıyor ve sub-resource'ları çekiyor. Bunun karşılığında bu işlem geri alınamaz. Shell bir kez wire'a çıktığında Nuxt status kodunu değiştiremez, header veya cookie ekleyemez ya da render ortasında cevabın bir redirect olması gerektiğine karar veremez.

Sessizce devre dışı bırakan altı route rule

Resmî 4.5 release notes'a atıfta bulunan dev.to yazısına göre, şu routeRules'lardan herhangi birini taşıyan route'lar herhangi bir uyarı veya hata olmadan otomatik olarak buffer'lı renderer'ı kullanıyor:

• redirect — tüm response için bir 3xx status'ü ve bir Location header'ı gerekir, bunlar 200 shell flush edildikten sonra verilemez
• cache — bir cache girdisi tam ve bitmiş bir payload tutmalıdır, bir sayfanın parçası buna uygun değildir
• isr — Incremental Static Regeneration tamamlanmış bir HTML artifact'ini diske veya CDN'e yazar, build artifact'ine uygulanan aynı kısıtlamadır
• swr — stale-while-revalidate, arka planda yeni bir tanesi yeniden üretilirken stale kopya olarak hizmet vermek için bütün bir response'a ihtiyaç duyar
• noScripts — hydration JavaScript'i olmadan tamamen statik çıktı üretir, streaming'in üzerine kurulduğu progressive hydration'ı ortadan kaldırır
• ssr: false — SPA moduna zorlar; sunucu neredeyse boş bir shell döner ve stream edilecek server-render'lı bir body yoktur

Yazarın argümanı, bu listenin keyfî değil yapısal olduğudur. Listedeki her kural tek bir bitmiş artifact teslim etmek zorundadır — cache'lenmiş bir payload, statik bir dosya, bir redirect, client-only bir shell — oysa streaming tam da eksik bir response'u wire'a koyarak çalışır. Pratik belirti masum görünür: yazının açılış senaryosunda, cache: { maxAge: 60 } kuralının arkasındaki bir fiyatlandırma sayfası, global bayrak etkin olmasına rağmen Time to First Byte'da hiç iyileşme göstermez, çünkü Nuxt bunu hiçbir şey söylemeden buffer'lamıştır. Yazı ayrıca route'ların route rules ile streaming'den nasıl açıkça çıkarılabileceğini de ele alıyor.

Crawler'lar da buffer'lı yolu alıyor

Route rules'lardan ayrı olarak, bot ve crawler'lara otomatik olarak buffer'lı response sunuluyor; böylece arama motorları, başa çıkmakta zorlanabilecekleri bir stream yerine tek bir, tamamen birleşmiş HTML belgesi alıyor. Yazının belirttiğine göre buradaki konfigürasyon yüzeyi hâlâ akışkan; Nuxt ekibi, seçenekleri — bot eşleştirme regex'i dahil — daha anlaşılır kılmak için yeniden adlandırıyor.

Denetlenmesi gereken geç yazma çökmesi

Daha sert başarısızlık modu ise sıradan koddan geliyor. Yazı, bir cookie ayarlayan bir request interceptor'ın — gündelik bir pattern — yukarıdaki geri alınamazlıkla karşılaşarak ERR_HTTP_HEADERS_SENT üretmesini anlatıyor; birçok ekibin tanımadığı bir hata bu. Bu bir Nuxt bug'ı değil: header'lar gönderildikten sonra runtime, bunlara yapılacak ek yazmaları reddeder.

Öneri, streaming'i geniş çapta devreye almadan önce geç response mutasyonlarını — status değişiklikleri, header yazmaları, cookie ayarlamaları, request lifecycle'ın derinliklerinde verilen redirect'ler — denetlemek ve bayrağı route'ları dönüştüren değil, onları uygun hâle getiren bir şey olarak görmek: Nuxt her request'i yine değerlendirir ve o anda streaming'in uygulanıp uygulanmayacağına karar verir.

Neden önemli

SSR streaming önemli bir performans kazanı olarak konumlanıyor ve bu sessiz geri dönüşler, ekiplerin onu etkinleştirip hızlı sayfalara sevinmesini ve sonra cache'lenmiş, ISR veya redirect'li route'larda hiçbir iyileşme görmemelerine şaşırmasını — ya da daha kötüsü, cookie-interceptor çökmesiyle doğrudan production'da karşılaşmasını sağlayabilir. Header'ların body tamamlanmadan commit edildiği bu temel kısıtlamayı anlamak, görünüşte keyfî bir istisna listesini öngörülebilir bir kurala dönüştürür. Bu ayrıca ekiplere somut bir kontrol listesi verir: kodun response'u mutate ettiği her yeri bulun, hangi route'ların altı kuraldan birini taşıdığını doğrulayın ve ancak o zaman Time to First Byte sayılarının hareket etmesini bekleyin.