Turbopack Disk Cache: next build'i Hızlandırma Rehberi

Next.js 16.3'ün en somut vaadi, "next build" süresinin ilk çalıştırmadan sonra tekrarlayan build'lerde belirgin şekilde düşmesi. Turbopack'in 16.1'den beri dev sunucusunda kullandığı disk tabanlı dosya sistemi cache'i, 3 Ağustos 2026'da yayınlanan 16.3 sürümüyle next build'e de taşındı ve varsayılan olarak açık geldi. Bu yazıda cache'in hangi iki ayrı config anahtarıyla çalıştığını, CI'da nasıl kalıcı hale getirileceğini, 8GB'lık bir VPS'te build-lock disiplininin neden hâlâ şart olduğunu ve deneysel Rust tabanlı React Compiler'ın getirdiği ek kazancı göreceksin.

💡 Pro Tip: turbopackFileSystemCacheForBuild varsayılan olarak açık geliyor; hiçbir şey yapmadan yalnızca Next.js 16.3'e yükseltmek ilk kazancı getiriyor — asıl iş CI'da .next/cache dizinini build'ler arası kalıcı tutmakta.

İçindekiler

• 16.3'te değişen iki şey
• Sürüm geçmişi
• Cache nerede tutuluyor, neyi invalidate ediyor
• CI'da cache'i taşımak
• 8GB sunucuda build: RAM ön-kontrolü ve build-lock zorunluluğu
• Ölçüm: cold vs cached build karşılaştırması
• Cache'in yalan söylediği durumlar ve temizleme
• Deneysel Rust React Compiler ile birleşik kazanç
• SSS
• Turbopack FileSystem cache nasıl açılır?
• next build neden hâlâ yavaş, cache neden ıskalıyor?
• Dev server'ın RAM tüketimi nasıl düşürülür?
• CI'da Turbopack cache'i nasıl kalıcı hale getirilir?
• Disk cache ile memory eviction aynı şey mi?
• turbopackFileSystemCacheForBuild'i ne zaman kapatmalıyım?
• Disk cache prod davranışını (çıktıyı) değiştirir mi?
• Sonuç
• Kaynaklar

16.3'te değişen iki şey

Next.js 16.3 duyurusu iki ayrı ama birbiriyle ilişkili özelliği aynı anda anons etti: "The disk caching feature that's been speeding up dev since 16.1 now works with next build and is enabled by default." Yani dev tarafındaki disk cache mekanizması artık build tarafında da çalışıyor ve ek bir ayar açmana gerek yok.

İkinci özellik ayrı bir mekanizma: turbopackMemoryEviction. Bu, 16.3.0'da deneysel olarak yayınlandı ve varsayılan modu 'auto'. Resmi dokümana göre bu ayarın etkisi yalnızca next dev oturumlarında geçerli ve disk cache'in açık olmasını şart koşuyor, çünkü bellekten tahliye edilen veri diskten geri okunuyor. Build tarafında ayrı bir bellek tahliye mekanizması yok.

Bu iki özelliği birbirine karıştırmamak önemli, çünkü ikisi de "cache" kelimesini paylaşıyor ama farklı problemleri çözüyor. Disk cache, derleme çıktısını yeniden hesaplamaktan kaçınmak için var — hem dev hem build'de işe yarıyor. Memory eviction ise yalnızca uzun süren dev oturumlarında RAM'in zamanla şişmesini önlemek için var ve build sürecinin bir parçası değil. 16.3'e yükseldiğinde ikisini de ayrı ayrı devre dışı bırakabilirsin ama varsayılan davranışları — ikisi de açık — çoğu proje için doğru başlangıç noktası.

Sürüm geçmişi

Cache'in build'e gelmesi bir gecede olmadı. Resmi config referansı şu kronolojiyi veriyor:

Bu satırı yazdığım anda (2026-09-23) npm registry'de next paketinin latest etiketi 16.3.6; canary etiketi ise 16.4.0-canary.40. Yani 16.4 henüz stabil değil, aktif geliştirme canary kanalında sürüyor. Güncel sürümü npm view next version ile kendin doğrula.

Cache nerede tutuluyor, neyi invalidate ediyor

İki ayrı anahtar, iki ayrı dizine yazıyor. turbopackFileSystemCacheForDev (varsayılan true) .next/dev/cache/turbopack altına, turbopackFileSystemCacheForBuild (varsayılan true) ise .next/cache/turbopack altına yazıyor. Tek bir birleşik turbopackFileSystemCache anahtarı yok; config referans sayfası bunu iki ayrı boolean olarak listeliyor.

Hangi girdi değiştiğinde cache'in ne kadarının geçersiz kaldığı resmi olarak belgelenmiş değil; pratikte güvenebileceğin davranış şu: disk cache açıkken Turbopack, yeni değişiklikleri derlemeden önce diskteki girdileri okuyor; değişmeyen artifact'ler yeniden üretilmek yerine diskten geliyor.

1# next.config.js dosyanda hangi cache'lerin açık olduğunu görmek için
2node -e "console.log(require('./next.config.js'))"

CI'da cache'i taşımak

Cache'in build'i hızlandırması tek bir koşula bağlı: .next/cache dizininin çalıştırmalar arasında korunuyor olması. Resmi doküman bunu net söylüyor: "Builds only get faster when that directory is restored before each build." Bu dizin restore edilmiyorsa, disk cache açık olsa bile her build sıfırdan başlar.

Self-hosted build'lerde — yani aynı çalışma dizinini build'ler arası tekrar kullanan sunucularda — cache otomatik olarak korunur. Konteynerize build'lerde durum farklı: her build temiz bir katmandan başladığı için .next/cache'i açıkça mount etmek ya da cache'lemek gerekiyor.

Next.js'in resmi "CI Build Caching" rehberi GitHub Actions için actions/cache kullanan bir adım öneriyor ve aynı yaklaşımı Vercel, CircleCI, Travis, GitLab, Netlify, AWS CodeBuild, Bitbucket, Heroku, Azure Pipelines ve Jenkins için de tarif ediyor — hepsi aynı .next/cache dizinini hedefliyor. Hangi sağlayıcıyı kullanırsan kullan, çözülmesi gereken soru aynı: build ortamı .next/cache'i bir sonraki çalıştırmaya taşıyor mu, taşımıyor mu. Vercel gibi platform build'lerinde bu genelde platformun kendi cache mekanizmasıyla otomatik oluyor; kendi CI runner'ını yönettiğin GitHub Actions, GitLab CI ya da Jenkins gibi ortamlarda bu adımı sen tanımlamak zorundasın.

1# GitHub Actions — .next/cache'i build'ler arası taşımak
2- name: Cache Next.js build output
3  uses: actions/cache@v4
4  with:
5    path: .next/cache
6    key: ${{ runner.os }}-nextjs-${{ hashFiles('**/package-lock.json') }}

Build ortamın .next/cache'i hiçbir zaman korumuyorsa — örneğin her seferinde tamamen temiz bir konteyner katmanından başlıyorsan — resmi öneri, boşuna cache yazmayı önlemek için turbopackFileSystemCacheForBuild: false yapmak.

1// next.config.js — build ortamı cache'i asla saklamıyorsa
2module.exports = {
3  experimental: {
4    turbopackFileSystemCacheForBuild: false,
5  },
6};

8GB sunucuda build: RAM ön-kontrolü ve build-lock zorunluluğu

Turbopack için resmi bir build-time bellek tepe ölçümü yok; 16.3 duyurusundaki %90'a varan bellek azalması rakamları next dev oturumlarına ait, build'e değil. Bu yüzden 8GB'lık bir VPS'te build koşarken güvenliğin kaynağı Next.js'in resmi bir garantisi değil, kendi operasyonel disiplinin.

Pratikte bu şu anlama geliyor: build'e başlamadan önce kullanılabilir RAM'i kontrol etmek ve aynı anda ikinci bir next build sürecinin çalışmadığından emin olmak (pgrep -f 'next build'). 8GB'lık bir sunucuda eşzamanlı iki build, birbirinin .next/standalone çıktısını yarıda kesebilir ve servisin MODULE_NOT_FOUND ile yeniden başlama döngüsüne girmesine yol açabilir. Disk cache'in kendisi bu riski büyütmez ya da küçültmez — cache diskte tutulan bir veri yapısıdır, ek RAM tepe kullanımı build'in normal derleme sürecinden gelir.

• RAM ön-kontrolü: build başlamadan minimum boş bellek eşiğini doğrula.
• Build-lock: pgrep ile eşzamanlı next build sürecini engelle.
• Swap payı: RAM'in üstüne bir swap katmanı bırak, build'in tepe noktasında OOM'a düşmesin.

Bu üç madde disk cache'in kendisiyle ilgili değil, sınırlı kaynaklı bir sunucuda herhangi bir Node.js build sürecini çalıştırmanın genel disiplini. Disk cache açıkken bile build, bağımlılık grafiğini bellekte kurup derlemeyi bellekte yürütüyor; cache yalnızca değişmeyen kısmın yeniden hesaplanmasını atlıyor, bellekte hiç yer kaplamıyor değil. Bu yüzden "cache açtım, artık daha az RAM ister" varsayımıyla build-lock'u ya da RAM ön-kontrolünü kaldırmak yanlış bir çıkarım olur — ikisi farklı problemleri çözüyor ve birbirinin yerine geçmiyor.

Aynı mantık swap için de geçerli: swap, build'in geçici tepe noktasını karşılamak için bir güvenlik payı sağlıyor, cache ise tekrar eden build'lerde toplam işi azaltıyor. 8GB ve altı bir sunucuda ikisini birlikte düşünmek, tek başına birine güvenmekten daha güvenli bir varsayılan.

Ölçüm: cold vs cached build karşılaştırması

Next.js 16.3 duyurusu üç gerçek proje ölçümünü tablo halinde paylaştı. Resmi rakamlar şöyle:

Duyuru metni ayrıca "…are seeing some projects with 5.5x faster builds on CI" diyor. Bu rakamı aktarırken dikkat edilmesi gereken nokta şu: 5.5× tek bir projede (vercel.com/geist) ölçülen en iyi durum; resmi örnekler arasındaki gerçek aralık 1.4×'ten 5.5×'e kadar değişiyor. Kendi projende beklenecek kazancı bu aralığın neresinde olacağını söylemek, kod tabanının büyüklüğüne ve build'ler arasında ne kadarının gerçekten değiştiğine bağlı — bu konuda resmi bir formül yayınlanmadı.

Kendi projenin gerçek kazancını görmek için en güvenilir yöntem, iki build'i kendi ölçmek. CI adımına basit bir zaman damgası eklemek yeterli:

1# CI adımında build süresini ölçüp loglamak için
2time next build

Bunu iki farklı koşulda çalıştır: bir kere .next/cache boşken (cold), bir kere restore edildikten sonra (cached). Aradaki fark, tabloyla verilen 1.4×-5.5× aralığından çok kendi kod tabanının build davranışını yansıtacak — bir sonraki değişiklikte hangi dosyaların yeniden derlendiği, cache'in isabet oranını doğrudan belirliyor.

Cache'in yalan söylediği durumlar ve temizleme

Next.js'in resmi dokümanlarında ayrı bir "bozuk cache" veya "stale cache" troubleshooting sayfası yok. Doğrulanmış olan iki davranış şu: cache restore edilmezse hiçbir hızlanma sağlamıyor (yukarıdaki CI bölümü) ve turbopackFileSystemCacheForBuild: false ile tamamen devre dışı bırakılabiliyor.

Şüphelendiğinde elindeki en güvenli araç, .next/cache dizinini silip build'i baştan çalıştırmak — bu, cache'i devre dışı bırakmadan tam bir cold build'e zorlar ve karşılaştırma için referans veriyor.

1# Şüpheli bir cache'i temizleyip tam cold build almak için
2rm -rf .next/cache
3next build

Bunun ötesinde bir "cache doğrulama" API'si ya da resmi bir debug komutu yok; referans yöntem .next/cache'i silip cold build almak.

Pratikte cache'in "yalan söylediğini" düşündüğün anların çoğu aslında CI bölümünde anlatılan senaryoya çıkıyor: cache hiç restore edilmemiş ya da yanlış anahtarla restore edilmiş. Bir sonraki adıma geçmeden önce şu iki soruyu sırayla sor: CI adımı .next/cache'i gerçekten geri yüklüyor mu, ve geri yüklenen cache güncel lockfile'a mı ait yoksa eski bir bağımlılık setine mi ait? Bu iki soru, "cache" bölümündeki config flag'lerinden önce kontrol edilmesi gereken ilk adım.

Deneysel Rust React Compiler ile birleşik kazanç

16.3 paketinin build hızını etkileyen bir diğer parçası, Turbopack'e entegre edilen deneysel Rust tabanlı React Compiler. Duyuru metnine göre büyük React uygulamalarında (Vercel'in v0 ürünü örnek verilmiş) erken testlerde %20-50 arası derleme kazancı gözlendi: "Promising early tests against large React apps like v0 showed compilation wins of 20-50%."

Stabil, Babel tabanlı React Compiler desteği zaten 16.0'dan beri mevcuttu. Rust tabanlı native versiyonu denemek için React Compiler'ı açman ve ek olarak deneysel turbopackRustReactCompiler flag'ini kullanman gerekiyor.

1// next.config.js — deneysel Rust React Compiler
2module.exports = {
3  reactCompiler: true,
4  experimental: {
5    turbopackRustReactCompiler: true,
6  },
7};

Bu iki kazanç birbirinden bağımsız: disk cache tekrar eden build'lerde değişmeyen kısmı atlıyor, Rust React Compiler ise değişen kısmın derlenme hızını artırıyor. Aynı build'de ikisini birlikte açmak birbirini dışlamıyor.

Bunu somutlaştırmak gerekirse: bir pull request'te yalnızca birkaç bileşen değiştiğinde, disk cache değişmeyen yüzlerce dosyayı yeniden derlemeden atlıyor; Rust React Compiler ise gerçekten değişen o birkaç bileşeni derlerken devreye giriyor. İki mekanizma da deneysel/yeni olduğundan, ikisini aynı anda büyük bir prod build'e almadan önce bir staging ortamında denemek makul bir sıra — özellikle turbopackRustReactCompiler henüz deneysel bir flag olduğu için.

SSS

Turbopack FileSystem cache nasıl açılır?

Next.js 16.1 ve üzeri sürümlerde dev cache (turbopackFileSystemCacheForDev), 16.3 ve üzeri sürümlerde ise build cache (turbopackFileSystemCacheForBuild) varsayılan olarak zaten açık geliyor; ayrı bir aktivasyon adımına gerek yok. İkisini de next.config.js içinde experimental altında false yaparak kapatabilirsin, aksi halde hiçbir ayar gerekmiyor.

next build neden hâlâ yavaş, cache neden ıskalıyor?

En sık neden, build ortamının .next/cache dizinini iki çalıştırma arasında korumaması. Özellikle konteynerize CI her seferinde temiz bir katmandan başlıyorsa cache hiç okunamaz. Çözüm, CI sağlayıcında bu dizini açıkça cache'lemek ya da mount etmek; bu mümkün değilse boşuna yazılan cache'i turbopackFileSystemCacheForBuild: false ile kapatmak.

Dev server'ın RAM tüketimi nasıl düşürülür?

Next.js 16.3'te Turbopack, disk cache ile birlikte çalışan yeni turbopackMemoryEviction mekanizmasıyla (varsayılan mod 'auto') dev bellek kullanımını büyük projelerde ciddi oranda azaltıyor; resmi örneklerde bu oran %90'a kadar çıkıyor. Ek bir aksiyon gerekmiyor, 16.3'e yükseltmek yeterli.

CI'da Turbopack cache'i nasıl kalıcı hale getirilir?

next build cache'i .next/cache altına yazılır; bu dizin iş akışları arasında korunmadıkça hiçbir hız kazancı sağlamaz. Self-hosted build'lerde bu genelde otomatik olur; konteynerize CI'larda manuel cache/mount konfigürasyonu şart.

Disk cache ile memory eviction aynı şey mi?

Hayır. Disk cache (turbopackFileSystemCacheForDev/ForBuild) derleme çıktısını diske yazıp okuyor; hem dev hem build'de çalışıyor. turbopackMemoryEviction ise yalnızca next dev oturumlarında bellekten veri tahliye eden ayrı bir mekanizma ve çalışabilmesi için disk cache'in açık olmasını şart koşuyor.

turbopackFileSystemCacheForBuild'i ne zaman kapatmalıyım?

Yalnızca build ortamının .next/cache dizinini hiçbir şekilde build'ler arası koruyamadığı durumlarda. Böyle bir ortamda cache açık kalırsa her build sonunda diske yazma maliyetine katlanırsın ama hiçbir zaman okuma tarafından fayda görmezsin — resmi öneri bu senaryoda flag'i false yaparak gereksiz yazmayı atlamak.

Disk cache prod davranışını (çıktıyı) değiştirir mi?

Resmi dokümanlar cache'i yalnızca bir derleme hızlandırma mekanizması olarak tanımlıyor; üretilen build çıktısının içeriğini değiştirdiğine dair bir ifade yok. Şüphe duyduğunda referans almanın en güvenli yolu, yukarıdaki "cache'i temizleme" adımıyla tam bir cold build alıp çıktıyı karşılaştırmak.

Sonuç

Next.js 16.3 ile gelen Turbopack disk cache, next build'i tek bir yükseltmeyle hızlandırabilecek nadir özelliklerden biri — ama gerçek kazancı yalnızca .next/cache dizinini CI'da kalıcı tutan ekipler görüyor. Resmi örnekler 1.4× ile 5.5× arasında bir aralık gösteriyor; kendi projendeki sayı bağımlılıklarının ve değişim sıklığının büyüklüğüne bağlı.

Ayrı sürüm geçişlerini ve etraftaki ekosistem kararlarını daha derin okumak istersen Next.js 16.3 Instant Navigations ve Cache Components rehberine, Edge Runtime'ın kaldırılıp Node'a geçiş sürecine, TypeScript 7 Go derleyicisine geçiş kararına ve Prisma 6.7-6.8'in Rust motoru sonrası değişimine göz atabilirsin. Bundler tarafında farklı bir eksende karar veriyorsan webpack'ten Vite'a geçiş rehberi de faydalı bir karşılaştırma sunuyor.

Kaynaklar

• Next.js 16.3 duyurusu — cache'in build'e gelişi, memory eviction rakamları ve CI ölçüm tablosu.
• Next.js 16.3 Turbopack detay yazısı — Rust React Compiler ve genişletilmiş bellek/CI verileri.
• turbopackFileSystemCache config referansı — iki ayrı anahtar, dizin yolları, sürüm geçmişi tablosu.
• turbopackMemoryEviction config referansı — deneysel bellek tahliye mekanizması ve dev-only kısıtı.
• Next.js CI Build Caching rehberi — GitHub Actions, GitLab, CircleCI ve diğer sağlayıcılar için kalıcı cache örnekleri.
• npm registry dist-tags: next — yazım anı (2026-09-23) itibarıyla latest sürüm doğrulaması.