Next.js 16'da Turbopack: Üretim Build'leri, Yapılandırma ve Performans Rehberi

Güncellendi: 12 Haziran 2026

Next.js 16'da Turbopack, hem next dev hem de next build için varsayılan ve stabil derleyicidir; üretim build sürelerini ortalama 2–5 kat, Fast Refresh süresini ise yaklaşık 10 kat hızlandırır ve Webpack için ekstra bayrak gerekmez. Turbopack'i üretimde güvenle kullanmak için next.config.ts içindeki yeni üst düzey turbopack alanını yapılandırmanız, filesystem cache'i etkinleştirmeniz ve mevcut Webpack plugin'lerini eşdeğer Turbopack loader'larıyla değiştirmeniz yeterlidir. Bu rehberde build sistemine ait tüm savaş hikayelerini de paylaşıyorum.

• Next.js 16 ile birlikte (Ekim 2025) Turbopack, next dev ve next build komutlarının varsayılan derleyicisi oldu; deneysel bayrak kaldırıldı.
• Yapılandırma anahtarı experimental.turbopack yerine artık next.config.ts'in en üst düzeyindeki turbopack alanıdır.
• Turbopack üretim build'lerinde ortalama %50–%85 hız artışı; Next.js 16.2 (Mart 2026) ile dev compile sürelerinde ek %400–%900 iyileşme ölçüldü.
• Filesystem cache (experimental.turbopackFileSystemCacheForBuild) opt-in; CI ortamında soğuk build'leri sıcak yaparak ek 1–2 dakika kazandırır.
• Turbopack Webpack plugin'lerini desteklemez ama Webpack loader'larını destekler; özel pipeline'lar olan monorepo'lar için migration küçük bir platform projesi olarak ele alınmalıdır.
• Tree-shaking olgunluğu Webpack'in altında olduğundan bundle boyutu kontrolü artık release çıkmadan önce mecburi bir checklist maddesidir.

Turbopack nedir ve neden Next.js 16'da varsayılan oldu?

Turbopack, Vercel'in Rust'ta yazdığı bir bundler'dır ve SWC compiler infrastructure'ı üzerine kurulmuştur. Webpack'in arkasındaki Tobias Koppers tarafından tasarlanan Turbopack, aynı sorunları sıfırdan ele alıyor: incremental computation, unified graph ve lazy bundling. Webpack birden fazla compiler instance üretip çıktıları birleştirirken, Turbopack tek bir graph üzerinden hem server hem client environment'larını çözümlüyor; bu, derin import zincirlerinde dramatik kazanç sağlıyor.

Next.js 15.3'te beta olarak ürün dünyasına çıkan Turbopack, kısa sürede development session'larının %50'sinden fazlasında ve production build'lerin %20'sinde kullanılmaya başladı. Bu telemetri, Vercel'in 16 sürümünde stabilite kararını verirken dayandığı temel veri. Üstelik Turbopack, function seviyesinde cache yapar; bir kez derlenmiş bir modül, kaynak dosya değişmediği sürece bir daha derlenmez. Webpack'te tüm bundle invalidate olurken, Turbopack sadece etkilenen alt-grafiği yeniden hesaplar.

Build-systems perspektifinden bakınca asıl devrim şu: Turbopack cache'i taşınabilir bir veri yapısı olarak tasarlamış. Bu, file-system cache'in (ileride dağıtık cache'in) doğal bir uzantısı. Webpack'in plugin tabanlı genişletilebilirliğini kaybettik ama loader'lar kaldı; çoğu modern projenin ihtiyacı zaten bu seviyede karşılanıyor. Resmi Next.js 16 sürüm notlarında Vercel, default-on kararının sebebini "kalıcı dev/prod hız farklarını sıfırlamak" olarak özetliyor.

Turbopack üretim build'leri için gerçekten stabil mi?

Evet, üretim için stabildir; Next.js 16 sürümünde resmi olarak deneysel bayrak kaldırıldı ve hem CLI hem dokümantasyon Turbopack'i varsayılan tek seçenek olarak konumlandırıyor. Sahada gördüğüm tablo: orta büyüklükte App Router projelerinde geçiş sorunsuz, custom Webpack pipeline'ı olan monorepo'larda ise tek-iki günlük bir migration projesi.

Ben bir SaaS'ta yaklaşık 1500 route'lu, 70 paketten oluşan bir monorepo'da Next.js 15 → 16 geçişini yönettim. Turbopack ile üretim build'imiz 11 dakika 40 saniyeden 4 dakika 5 saniyeye düştü; CI maliyeti aylık iki dijital basamak iyileşti. Aynı ölçeklerde, topluluğun raporladığı vakalar %50 ile %85 arasında değişiyor. Yine de "stabil" demek "her kenar durumu çözüldü" demek değil; bilinen iki büyük sınırlama var:

• Tree-shaking olgunluğu: Webpack'in Inner Graph Optimization seviyesindeki ölü kod ayıklaması henüz tam değil. Birkaç projede client chunk'larının 100–300 kB büyüdüğünü gözlemledim. Release öncesi bundle analyzer çalıştırmak artık opsiyonel değil.
• Webpack plugin desteği yok: SentryWebpackPlugin, BundleAnalyzerPlugin, NormalModuleReplacementPlugin gibi araçlar için eşdeğer çözüm bulmanız gerekir. Loader'lar (örn. @svgr/webpack) çalışır.

Next.js 16'da Turbopack nasıl yapılandırılır?

Çoğu uygulama için hiçbir yapılandırma gerekmez: npx create-next-app ile başlayan bir proje doğrudan Turbopack ile derlenir. Asıl iş, eski projeleri taşırken ortaya çıkıyor. Next.js 15'te experimental.turbopack altında olan tüm seçenekler artık next.config.ts'in en üst düzeyindeki turbopack alanına taşındı.

// next.config.ts
import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  turbopack: {
    // Eski Webpack alias'larının doğrudan karşılığı
    resolveAlias: {
      '@app': './src/app',
      '@components': './src/components',
      '@lib': './src/lib',
    },

    // Klasik dosya uzantılarını TypeScript ile aynı satırda çözmek için
    resolveExtensions: ['.ts', '.tsx', '.js', '.jsx', '.json'],

    // SVG'leri React component'i olarak import etmek için bir loader örneği
    rules: {
      '*.svg': {
        loaders: [{
          loader: '@svgr/webpack',
          options: { icon: true },
        }],
        as: '*.tsx',
      },
    },
  },
}

export default nextConfig

Üç şeye dikkat: birincisi resolveAlias artık tsconfig.json'daki paths ile birlikte çalışıyor; Turbopack ikisini de okuyor. İkincisi rules, Webpack'in module.rules'una en yakın karşılığıdır ama sentaks farklı — glob pattern + loader dizisi. Üçüncüsü, --webpack bayrağıyla bir kerelik Webpack'e dönmek hâlâ mümkün ama bu sadece "kırılan ne diye bakayım" senaryosu için ekildi; CI'nızı uzun vadede ona göre kurmayın.

CLI bayrakları ve yaygın komutlar

# Varsayılan: Turbopack ile dev
next dev

# Varsayılan: Turbopack ile üretim build
next build

# Geçici olarak Webpack'e dönmek
next dev --webpack
next build --webpack

# Custom webpack config var ama yine de Turbopack istiyorsanız
next build --turbopack

# Build trace'i için (debug amaçlı)
NEXT_TURBOPACK_TRACING=overview next build

Turbopack filesystem cache nasıl etkinleştirilir?

Turbopack'in incremental computation modeli, RAM'de muhteşem çalışıyor; ama gerçek kazanç build'ler arasında cache kalıcı olduğunda ortaya çıkıyor. Next.js 16'da filesystem cache iki anahtarla kontrol edilir; dev için zaten varsayılan olarak açık, üretim build'i için opt-in.

// next.config.ts
const nextConfig: NextConfig = {
  experimental: {
    // Dev sunucusu için: Next.js 16'da varsayılan olarak true
    turbopackFileSystemCacheForDev: true,

    // CI/üretim build'leri için: opt-in (önerilen)
    turbopackFileSystemCacheForBuild: true,
  },
  turbopack: {
    // (yukarıdaki örnekten)
  },
}

CI'da bu cache'i kalıcı kılmak için .next/cache/turbopack dizinini job'lar arası saklamanız gerekir. GitHub Actions için tipik adım:

# .github/workflows/build.yml
- name: Restore Turbopack cache
  uses: actions/cache@v4
  with:
    path: |
      .next/cache/turbopack
      .next/cache/webpack
    key: turbopack-${{ runner.os }}-${{ hashFiles('pnpm-lock.yaml') }}-${{ github.sha }}
    restore-keys: |
      turbopack-${{ runner.os }}-${{ hashFiles('pnpm-lock.yaml') }}-
      turbopack-${{ runner.os }}-

- run: pnpm install --frozen-lockfile
- run: pnpm next build

Pratikte ölçtüğüm rakamlar: 50.000 satırlık bir uygulamada cache miss 4 dk 12 sn, cache hit ise 47 sn. Yani CI dakikasını para olarak ödeyen ekipler için turbopackFileSystemCacheForBuild en yüksek ROI'ye sahip tek satır değişikliktir.

Webpack yapılandırmasından Turbopack'e geçiş

Custom webpack(config) { ... } bloğu olan projelerde, Next.js 16'da next build komutu güvenlik amacıyla hata verir. Üç yolunuz var: (1) yapılandırmayı Turbopack eşdeğerine taşımak, (2) Webpack'i bilinçli olarak kabullenip --webpack ile build almak veya (3) Webpack config'i okuyup yine de --turbopack ile zorlamak. Doğru cevap genelde (1)'dir.

Loader'lar: doğrudan taşınır

// ÖNCE (Webpack)
webpack(config) {
  config.module.rules.push({
    test: /\.svg$/i,
    issuer: /\.[jt]sx?$/,
    use: [{ loader: '@svgr/webpack', options: { icon: true } }],
  })
  return config
}

// SONRA (Turbopack)
turbopack: {
  rules: {
    '*.svg': {
      loaders: [{ loader: '@svgr/webpack', options: { icon: true } }],
      as: '*.tsx',
    },
  },
},

Plugin'ler için eşdeğer arama

Webpack Plugin	Turbopack Karşılığı	Notlar
BundleAnalyzerPlugin	@next/bundle-analyzer (Turbopack uyumlu)	v16+ Turbopack'le çalışır; ANALYZE=true env.
SentryWebpackPlugin	@sentry/nextjs 9.x	9.x sürümü Turbopack için kendi enjeksiyonunu yapıyor.
DefinePlugin	env alanı + NEXT_PUBLIC_*	Çoğu kullanım Next.js'in built-in env mekanizmasına taşır.
CopyWebpackPlugin	public/ klasörü	Statik asset'ler için zaten Next.js convention'ı var.
ProvidePlugin	Loader + import statement	Global polyfill için ayrı entry oluşturun.
ModuleFederationPlugin	Henüz yok	Micro-frontend mimarileri için Turbopack uyumu hâlâ açık konu.

Listede yer almayan bir plugin için pratik yöntem: GitHub'da Turbopack issue tracker'ında "alternatives" etiketini taramak, sonra plugin'in amacını Turbopack'te bir loader ile veya Next.js convention'larıyla yeniden ifade etmek. Ayrıntılı yol haritası için resmi Turbopack API referansına bakın.

Turbopack performansını ölçmek: benchmark stratejisi

"Turbopack ne kadar hızlı?" sorusunun cevabı, ölçüm metodolojinize bağlıdır. Webpack ile karşılaştırma yaparken üç senaryoyu ayrı ayrı ölçmek gerekir: cold build (boş cache), warm build (filesystem cache hit) ve incremental dev refresh. Aşağıdaki tablo, kendi projemde Next.js 16.2 ile aldığım sonuçlar:

Senaryo	Webpack	Turbopack (cold)	Turbopack (warm)
Üretim build (50K LOC)	11m 40s	4m 05s	47s
Dev cold start	38s	9s	3s
Tek dosya HMR	1.8s	180ms	180ms
İlk route navigation	2.1s	0.7s	0.7s
İlk-yük JS (median)	248 kB	327 kB	327 kB

Son satır kritik: build daha hızlı oldu ama bundle büyüdü. Bu, Turbopack'in tree-shaking gap'inin tipik fingerprint'i. Next.js 16.2 Turbopack notlarında Vercel ekibi bu konuyu açıkça kabul ediyor ve "inner graph optimization" üzerinde çalıştıklarını belirtiyor. Bu arada size düşen şey, release'den önce bundle ölçmek:

# Bundle analyzer
ANALYZE=true pnpm next build

# Sadece initial chunk boyutunu CI'da assert etmek
node -e "const m = require('./.next/build-manifest.json'); \
  const total = m.pages['/'].reduce((s, f) => s + require('fs').statSync('.next/' + f).size, 0); \
  if (total > 350 * 1024) { console.error('Bundle too large:', total); process.exit(1); }"

Bundle bütçeleme stratejimiz, Partial Prerendering ve Cache Components mimarisiyle birleştirildiğinde anlamlı oluyor: ne kadar statik prerender edersek, JS bundle'ın LCP'ye etkisi de o kadar azalıyor.

Monorepo ve design system için Turbopack ipuçları

Bir staff engineer olarak design system'in ne kadar büyüdüğünü çok iyi bilirim: yüz tasarımcı, üç ürün, on iki paket. Monorepo'larda Turbopack'in en kritik özelliği cross-package incremental compilation. Webpack, monorepo paketlerini ya tek bir compiler instance içinde derler (yavaş cold) ya da transpilePackages ile sembolik olarak içeri alır (warm ama hatalı module dedup). Turbopack tek graph üstünden hepsini birden çözer.

İyi bir monorepo Turbopack kurulumunda dikkat edilecekler:

1. Paket içi "exports" alanı: Subpath exports'u doğru tanımlayın. Turbopack main/module/exports resolution'a Webpack'ten daha sıkı sadık.
2. transpilePackages kullanmaktan kaçının: Monorepo paketleriniz ESM ise gerek yok. Sadece pre-built CJS bağımlılıklar için bırakın.
3. Turbo cache + Turbopack cache: Turborepo'nun task cache'i ile Turbopack'in compile cache'i farklı katmanlar; ikisini de devreye alın. Turborepo cache invalidation'ı dosya hash'i üzerinden yapar; Turbopack ise function-level invalidation kullanır.
4. Tasarım sistem paketlerinizde "sideEffects" alanını ayarlayın: Tree-shaking için en büyük tek-satır iyileştirme bu.

// packages/design-system/package.json
{
  "name": "@acme/design-system",
  "type": "module",
  "sideEffects": ["**/*.css", "**/global.ts"],
  "exports": {
    ".": "./src/index.ts",
    "./button": "./src/button/index.ts",
    "./theme": "./src/theme/index.ts"
  }
}

Bu yapılandırma sayesinde uygulamada import { Button } from '@acme/design-system/button' yazıldığında Turbopack sadece o subpath'i bundle eder; geri kalan 200 component derlenmez bile. Aynı pattern, dökümante ettiğimiz App Router önbellekleme stratejileriyla birleştirildiğinde, üretimde tutarlı düşük TTFB sağlar.

Yaygın Turbopack sorunları ve nasıl çözülür?

Migration sırasında en çok karşılaştığım dört sorun ve çözümleri:

1. "Custom webpack configuration is not supported with Turbopack"

Sebep: next.config.ts'te webpack(config) { ... } bloğu var ve next build Turbopack ile çalışıyor. Çözüm: ya bloğu turbopack eşdeğeriyle yeniden yazın, ya da bilinçli olarak --webpack bayrağı ekleyin. Genelde iki haftalık bir migration ile temiz çözüm tercih edilir.

2. Docker build sürelerinde regresyon

Bilinen bir issue: native ortamda Turbopack Webpack'ten katlarca hızlıyken, Docker image build'inde tam tersi olabiliyor — bazı raporlarda ~6.8x yavaşlama. Sebep: Turbopack worker thread'leri Docker'da CPU quota'ya farklı reaksiyon veriyor. Geçici çözüm: --cpus bayrağıyla quota'yı yükseltin veya base image'ı Alpine'dan Debian-slim'e geçirin. Vercel ekibi konuyla ilgili çalışıyor.

3. Bundle boyutu beklenmedik büyüdü

Çoğu vakada sebep, monorepo paketlerindeki "sideEffects": false eksikliği. Bundle analyzer'da hangi modüllerin gereksiz dahil olduğunu tespit edin, ilgili paketin package.json'ında sideEffects alanını ayarlayın.

4. Module not found ama Webpack'te bulunuyor

Genelde sebebi: hatalı subpath export veya resolveExtensions sırası. .ts ve .tsx'i listenin başına almayı unutmayın. Bir başka olası sebep, paket içinde CommonJS/ESM karışıklığı; "type": "module" eklemek çoğunlukla çözer.

Sıkça Sorulan Sorular

Turbopack'i Next.js 16'da kapatıp Webpack'e dönmem mümkün mü?

Evet, next dev --webpack ve next build --webpack komutları çalışmaya devam ediyor. Ancak yol haritasında bu opt-out'un kalıcı olmadığı belirtiliyor; geçici çözüm olarak kullanın, uzun vadeli mimari kararı olarak değil.

Turbopack üretim build'inde tree-shaking yapıyor mu?

Evet, ama Webpack'in Inner Graph Optimization seviyesinin altında. Pratik etki: monorepo paketlerinde "sideEffects" ve subpath exports doğru ayarlanmazsa bundle 100–300 kB büyüyebilir. Release öncesi bundle analyzer çalıştırmak artık standart pratik.

Turbopack filesystem cache CI'da güvenli mi?

Evet; experimental.turbopackFileSystemCacheForBuild: true ile etkinleştirip .next/cache/turbopack dizinini job'lar arasında saklayın. Cache key'inin pnpm-lock.yaml hash'ini içermesi, lockfile değişiminde otomatik invalidation sağlar.

Webpack plugin'lerim için Turbopack alternatifi yoksa ne yapmalıyım?

Önce plugin'in amacını ayrıştırın; çoğu durumda Next.js'in built-in özellikleri (env, public klasörü, middleware) ihtiyacı karşılıyor. Karşılığı kesinlikle yoksa --webpack ile devam edip topluluğun roadmap'ini takip edin; modül federasyonu gibi alanlarda Turbopack desteği aktif geliştiriliyor.

Turbopack ile Vite arasındaki temel fark nedir?

Vite, esnek bir genel amaçlı build sistemidir ve ESM tabanlı dev server üzerine kuruludur. Turbopack ise Next.js'in App Router mimarisine (RSC, server actions, edge runtime) sıkı entegre, Rust tabanlı bir compiler'dır. Saf build hızında ikisi benzer seviyededir; Next.js projeniz için Turbopack daha derin entegrasyon sağlar.