Webpack'ten Vite'a Geçiş: 2026 Adım Adım Migrasyon Rehberi

Webpack ile büyümüş bir projeyi Vite'a taşımak, config yüzeyini küçültmenin ve dev sunucusu açılışını hızlandırmanın doğrudan yolu. Bu rehber, webpack config'indeki her parçayı (entry, output, loader, plugin, alias, env) Vite karşılığıyla eşleştirip adım adım geçişi anlatıyor; kaynak yalnızca resmi Vite ve webpack dokümantasyonu.

💡 Pro Tip: Geçişe npm install vite --save-dev ile başlamadan önce webpack config dosyanızın tam bir kopyasını ayrı bir branch'te tutun — loader/plugin eşlemesini yaparken referans olarak geri dönmen gerekecek.

İçindekiler

• Neden Geçiş: Dev Server ve Build Farkı
• Envanter: webpack Config'inde Ne Var
• Ortam Değişkenleri Eşlemesi
• Adım 1-6: Migrasyon
• Adım 1 — Paket Değişimi
• Adım 2 — index.html'i Köke Taşı
• Adım 3 — Ortam Değişkenlerini VITE_ Önekine Taşı
• Adım 4 — Alias/Resolve Ayarlarını Taşı
• Adım 5 — CSS/Asset Importlarını Sadeleştir
• Adım 6 — Legacy Tarayıcı Desteği
• Sık Kırılmalar
• Test: Dev + Prod Build Farkları
• Rolldown/Vite Sürüm Notu
• Ne Zaman GEÇMEMELİ
• SSS
• Webpack projesi Vite'a nasıl taşınır?
• Vite'a geçişte en sık kırılan şeyler nelerdir?
• Vite webpack'ten ne zaman daha iyi bir seçim değildir?
• `VITE_` önekini unutursam ne olur?
• Güncelleme (Eylül 2026)
• Sonuç
• Kaynaklar

Neden Geçiş: Dev Server ve Build Farkı

Vite'ın resmi "Getting Started" sayfası, aracı iki ayrı parça olarak tanımlar: native ES modüllerini zenginleştirilmiş özelliklerle sunan bir dev server ve kodu üretimde paketleyen bir build komutu. "Why Vite" sayfasındaki açıklama şöyle: bağımlılıklar bir kere pre-bundle edilir, projenin kendi kaynak kodu ise doğrudan native ESM üzerinden tarayıcıya servis edilir. Bu, webpack'in "önce her şeyi tek bir bundle grafiğinde işle, sonra sun" modelinden temelde farklı bir yaklaşım.

Üretim tarafında Vite 8'den itibaren build komutu kodu Rolldown ile paketliyor. Rolldown'ın kendi sitesi bunu "Vite 8+'ı güçlendiren birleşik bundler" (Designed for Vite — The unified bundler powering Vite 8+) olarak tanımlıyor; aracı ayrıca nitel olarak "Rolldown, on binlerce modülü zorlanmadan işler" (handles tens of thousands of modules without breaking a sweat) diye tanımlıyor.

Pratikte bu şu anlama geliyor: npm run dev ile açtığın sunucu artık dosyaları önceden tek bir grafik halinde işlemiyor, isteğe bağlı (on-demand) derliyor — büyük projelerde ilk açılışta hissedeceğin fark budur. vite CLI komutu da bunu yansıtıyor: vite dev ve vite serve, sade vite komutunun takma adlarıdır (aliases).

Envanter: webpack Config'inde Ne Var

Geçişe başlamadan önce webpack config'ini resmi "Concepts" sayfasındaki altı çekirdek kavrama göre envanterle: Entry, Output, Loaders, Plugins, Mode, Browser Compatibility. webpack'in varsayılan entry noktası ./src/index.js, varsayılan output ise ./dist/main.js (+ ./dist klasörü). Aşağıdaki tablo her kavramın Vite karşılığını gösteriyor.

Bu envanter çıkarma adımını atlama — geçişin çoğu sorun kaynağı, "hangi webpack özelliği hangi Vite mekanizmasına karşılık geliyor" sorusunu tek tek yanıtlamadan doğrudan config dosyasını kopyala-yapıştır yapmaktan çıkar. Özellikle loader zincirinde iç içe geçmiş, projeye özel dönüştürme adımların varsa (ör. özel bir SVG-to-component loader'ı ya da build-time kod üreteci), bunların hangi paket tarafından sağlandığını ve o paketin Vite plugin API'siyle (Rollup plugin arayüzüyle uyumlu) resmi bir Vite plugin'i olup olmadığını tek tek kontrol et. Yoksa, o adımı ayrı bir Node script'i olarak build öncesine (prebuild) taşımak, Vite'a özel bir plugin yazmaktan çoğu zaman daha az riskli bir geçiş yoludur.

Ortam Değişkenleri Eşlemesi

Vite'ın env sayfası nettir: yalnızca VITE_ önekli değişkenler import.meta.env üzerinden client koduna sızar; diğerleri sunucu tarafında kalır. Dosya yükleme sırası önceliğe göre şöyle: .env → .env.local → .env.[mode] → .env.[mode].local — moda özel dosya, genel olandan daha yüksek önceliklidir. Ayrıca import.meta.env.MODE, taban url sabiti, .PROD, .DEV, .SSR yerleşik sabitler olarak gelir.

Adım 1-6: Migrasyon

Adım 1 — Paket Değişimi

webpack, webpack-cli, webpack-dev-server ve ilgili loader'ları kaldırıp Vite'ı ekle:

1npm uninstall webpack webpack-cli webpack-dev-server
2npm install vite --save-dev

package.json script'lerini güncelle: webpack serve yerine vite, webpack --mode production yerine vite build.

Adım 2 — index.html'i Köke Taşı

webpack projelerinde index.html genelde public/ altındadır ve script etiketini build sonrası bundler ekler. Vite'da index.html proje kökünde durur ve entry'yi doğrudan sen işaret edersin:

1<!doctype html>
2<html>
3  <body>
4    <div id="root"></div>
5    <script type="module" src="/src/main.tsx"></script>
6  </body>
7</html>

Bu adımda dikkat edilmesi gereken nokta, <script> etiketinin type="module" özniteliğiyle işaretlenmesi — Vite dev sunucusu isteği bu şekilde native ESM olarak yakalar ve dosyayı anlık dönüştürür. webpack projelerinden gelenler için alışılmadık gelebilir: artık HtmlWebpackPlugin gibi bir plugin'in script etiketini build sırasında enjekte etmesine gerek yok, script etiketini sen elle, kaynağı gösterecek şekilde yazıyorsun.

Adım 3 — Ortam Değişkenlerini VITE_ Önekine Taşı

process.env. ile okuduğun değişkenleri import.meta.env. üzerinden, VITE_ önekiyle yeniden adlandır (önek olmayanlar client'a sızmaz — bu bilinçli bir güvenlik sınırı). Bu adımı yaparken projendeki her process.env. çağrısını tek tek arayıp listele; sunucu tarafında kalması gereken sırları (API anahtarları, veritabanı bağlantı dizeleri) yanlışlıkla VITE_ önekiyle işaretleme, çünkü önekli her değişken build çıktısına gömülür ve tarayıcıdan okunabilir hale gelir.

Adım 4 — Alias/Resolve Ayarlarını Taşı

webpack'teki resolve.alias girdilerini vite.config.ts içinde resolve.alias olarak yeniden yaz:

1import { defineConfig } from "vite";
2import { fileURLToPath } from "node:url";
3 
4export default defineConfig({
5  resolve: {
6    alias: {
7      "@": fileURLToPath(new URL("./src", import.meta.url)),
8    },
9  },
10});

(webpack'ten gelen, package.json'da "type": "module" olmayan CJS tabanlı projelerde __dirname doğrudan çalışır; ama vite.config.ts genelde ESM olarak yüklendiği için yukarıdaki fileURLToPath deseni daha güvenlidir.)

Adım 5 — CSS/Asset Importlarını Sadeleştir

Vite, .css importlarını otomatik olarak bir <style> etiketiyle enjekte eder ve HMR desteği sağlar; .module.css uzantılı dosyalar otomatik CSS Modules olarak işlenir. webpack'teki style-loader + css-loader + css-loader?modules zincirinin çoğu bu adımda gereksizleşir — config'inden silebilirsin.

Adım 6 — Legacy Tarayıcı Desteği

Eski tarayıcı hedefliyorsan @vitejs/plugin-legacy ekle (npm registry'de güncel sürüm 8.2.3, 6 Ağustos 2026'da yayınlandı). Bu, webpack + Babel + browserslist zincirinin Vite karşılığıdır:

1import { defineConfig } from "vite";
2import legacy from "@vitejs/plugin-legacy";
3 
4export default defineConfig({
5  plugins: [legacy({ targets: ["defaults", "not IE 11"] })],
6});

Bu altı adımı sırayla tamamladıktan sonra projenin webpack config dosyasını silmeden bırakmanı öneririm — birkaç hafta boyunca yan yana çalıştırıp (ör. eski build script'i npm run build:legacy olarak) çıktı boyutlarını ve davranış farklarını karşılaştırmak, geçişin gerçekten tam olduğunu doğrulamanın en güvenli yolu. Eski config'i sildiğin an, unuttuğun bir loader zincirini fark etmen çok daha zorlaşır.

Sık Kırılmalar

• require() çağrıları: Vite native ESM üzerine kurulu; CommonJS-only bağımlılıklar dependency optimizer aşamasında dönüştürülür. Vite 8'de bu dönüştürme artık esbuild yerine Rolldown ile yapılıyor — resmi migration sayfası "Rolldown is now used for dependency optimization instead of esbuild" diyor.
• process.env. okumaları: Yalnızca VITE_ önekli değişkenler client'a taşınır; öneksiz olanlar undefined döner. Sunucu-only sırları önekli yapma — bu bilinçli bir sızıntı önleme kuralı.
• Dinamik import globları: webpack'teki require.context deseni Vite'da import.meta.glob() ile karşılanır; birebir aynı API değil, taşırken glob deseni yeniden yazman gerekir.
• TypeScript tip kontrolü beklentisi: Vite yalnızca .ts dosyalarını transpile eder, tip kontrolü yapmaz (resmi ifade: "does NOT perform type checking"). tsconfig.json'da "isolatedModules": true zorunlu, çünkü Oxc transformer tip bilgisi olmadan çalışır.
• optimizeDeps.esbuildOptions kullanımı: Bu alan deprecated; migrasyonda optimizeDeps.rolldownOptions'a geçmen resmi olarak öneriliyor.

Bu beş kırılma noktasının ortak özelliği, hiçbirinin build sırasında net bir hata mesajıyla kendini göstermemesi — çoğu ya sessizce undefined döner (env değişkenleri), ya dev'de çalışıp build'de kırılır (dinamik glob'lar), ya da yalnızca tsc ayrı çalıştırıldığında ortaya çıkar (isolatedModules uyumsuzlukları). Bu yüzden geçiş PR'ında yalnızca "build başarılı" kontrolüne güvenme; her kırılma noktası için ayrı bir manuel test adımı ekle.

Test: Dev + Prod Build Farkları

Vite'ın dev sunucusu ile vite build çıktısı farklı yollardan geçtiği için (dev: native ESM üzerinden anlık dönüştürme; build: Rolldown ile paketleme) iki ortamı da ayrı doğrulaman gerekir. Resmi dokümantasyon, tip hatalarının dev sırasında yakalanmayacağını hatırlatıp üretim build'i öncesi ayrı bir adım önerir: "For production builds, you can run tsc --noEmit in addition to Vite's build command." Bunu CI adımına ekle:

1tsc --noEmit && vite build

Build çıktısını yerel olarak doğrulamak için Vite'ın CLI'sindeki önizleme komutunu kullanabilirsin:

1vite build
2vite preview

Bu adım, yalnızca dev sunucusunda çalışıp build çıktısında kırılan importları (ör. dinamik glob desenleri, yanlış alias çözümlemesi) yakalamak için faydalıdır; tsc --noEmit ile birlikte CI'ye eklemen önerilir.

Rolldown/Vite Sürüm Notu

Bu rehberin yazıldığı 16 Eylül 2026 itibarıyla npm registry'de vite paketinin güncel sürümü 8.3.0 (10 Eylül 2026 yayın); Vite 8.0.0 ilk olarak 12 Mart 2026'da yayınlandı. Migration guide'a göre Vite 8, esbuild ve Rollup yerine Rolldown ve Oxc tabanlı araçları kullanıyor: bağımlılık ön-paketleme Rolldown ile, JavaScript dönüştürme ve minifikasyon Oxc ile yapılıyor.

Ne Zaman GEÇMEMELİ

Aşağıdaki üç durum geçişte ek mühendislik yükü getirir:

• Ağır, native ESM'e taşınamayan CommonJS bağımlılık grafiği: Dependency optimizer bunları dönüştürmeye çalışır ama derin, döngüsel require() zincirleri manuel müdahale gerektirebilir.
• isolatedModules ile uyumsuz TypeScript kalıpları: const enum, bazı namespace kullanımları gibi tip-bilgisine bağımlı özellikler Oxc'nin transpile-only modeliyle doğrudan çalışmayabilir; önce tsc --noEmit ile projeni test et.
• Çok özelleşmiş webpack loader zincirleri: Şirket-içi, dokümante edilmemiş loader'lara bağımlı build adımların varsa, Vite plugin API'sine taşımadan önce ayrı bir kanıt-of-concept yap.

Bu üç durumun ortak noktası, geçişin teknik olarak imkânsız olmaması ama ek mühendislik yükü getirmesi. Bu yükü baştan kabul edip planlıyorsan geçiş yine de mantıklı olabilir; tek riskli olan, bu maddelerin hiçbirini fark etmeden geçişe başlayıp yarı yolda config'i ikiye bölmüş halde kalmaktır.

SSS

Webpack projesi Vite'a nasıl taşınır?

Önce webpack config'ini entry/output/loader/plugin/mode olarak envanterle, ardından vite paketini kurup index.html'i proje köküne taşı, process.env. okumalarını VITE_ önekiyle import.meta.env.'e çevir, alias'ları vite.config.ts içinde resolve.alias olarak yeniden yaz ve gerekiyorsa @vitejs/plugin-legacy ekle. En izole modülden başlayıp vite build + tsc --noEmit ile doğrulayarak ilerlemek, tüm projeyi tek seferde taşımaktan daha güvenlidir.

Vite'a geçişte en sık kırılan şeyler nelerdir?

En sık kırılan noktalar: öneksiz process.env. okumaları (client'a sızmaz, undefined döner), require.context ile yazılmış dinamik import glob'ları (import.meta.glob()'a yeniden yazılmalı), tip bilgisine bağımlı bazı TypeScript kalıpları (isolatedModules: true zorunluluğu nedeniyle) ve derin CommonJS bağımlılık zincirleri.

Vite webpack'ten ne zaman daha iyi bir seçim değildir?

Resmi kaynaklarda doğrudan bir karşı-öneri yok; ancak çok özelleşmiş, dokümante edilmemiş webpack loader zincirlerine bağımlı bir proje ya da isolatedModules ile uyumsuz derin TypeScript kalıpları kullanan bir kod tabanın varsa, geçişten önce küçük bir kanıt-of-concept modülüyle riskleri ölçmen gerekir.

`VITE_` önekini unutursam ne olur?

Değişken client koduna hiç ulaşmaz, import.meta.env içinde undefined olarak görünür; bu build hatası değil sessiz bir davranış farkıdır, bu yüzden env taşıma adımını checklist'e eklemek önemlidir.

Güncelleme (Eylül 2026)

Bu rehberi hazırlarken Eylül 2026 içinde doğrulanması gereken üç nokta çıktı, aşağıya kaynağıyla birlikte ekliyorum:

• Vite 8.3.0 (10 Eylül 2026): Minör özellik + düzeltme sürümü; migrasyon adımlarını etkilemiyor. Değişiklik listesinden öne çıkanlar: build sırasında daha önce görülmüş preload bağımlılıklarının performans için tekrar işlenmemesi (#23446), yalnızca tam node_modules yol segmentlerinin bağımlılık sayılması (#23437), proxy context matcher'larının sunucu oluşturulurken önceden derlenmesi (#23263) ve code-frame konumlarında CRLF satır sonlarının doğru işlenmesi (#23219). Kaynak: github.com/vitejs/vite/releases.
• rolldown-vite paketi arşivli durumda: GitHub'da repo arşivlenmiş görünüyor, ancak Vite'ın resmi migration kılavuzu rolldown-vite paketini hâlâ Vite 8'e geçişte isteğe bağlı bir ara adım olarak listeliyor; doğrudan güncel Vite 8.x'e geçmek de geçerli bir yol. Kaynak: github.com/vitejs/rolldown-vite, vite.dev/guide/migration.
• webpack 6 henüz çıkmadı: Bu rehberi okurken "webpack 6" varsayımıyla karşılaşırsanız güncel değildir — webpack'in güncel majör sürümü hâlâ 5.x serisi (5.111.0, 14 Eylül 2026). Kaynak: registry.npmjs.org/webpack.

Sonuç

Webpack'ten Vite'a geçiş, kod tabanını yeniden yazmak değil, config'ini altı çekirdek kavram (entry, output, loader, plugin, mode, browser compatibility) üzerinden yeniden eşlemek. En kritik üç nokta: VITE_ önekiyle env taşıma, isolatedModules: true ile TypeScript uyumu ve index.html'in köke taşınması. Modül modül ilerleyip her adımda tsc --noEmit + vite build ile doğrulamak, sürprizleri küçük tutar. İki aracın özellik düzeyinde tablolu karşılaştırması için webpack vs Vite sayfasına bakabilirsin.

Next.js tarafında build/runtime katmanındaki benzer değişiklikleri incelemek istersen Next.js 16.3 Instant Navigations ve Cache Components Rehberi ve Next.js 16.3'te runtime='edge' Bitti: Node'a Dönüş yazılarına bakabilirsin. TypeScript derleyici tarafındaki paralel dönüşüm için TypeScript 7 Çıktı: 10x Hızlı Ama ESLint Kırılıyor yazısı faydalı olacaktır. Full-stack araç zincirinin veritabanı katmanını güncelliyorsan Prisma 6'dan 7'ye Geçiş: Rust Motoru Gitti, Ne Değişti? rehberine de göz at. iOS tarafında benzer bir build-pipeline modernizasyonu için Xcode Cloud Pipeline Optimization: Build Times, Caching ve Cost 2026 yazısını inceleyebilirsin.

Kaynaklar

• Vite — Getting Started — dev server ve build komutunun resmi tanımı, vite dev/vite build ayrımı
• Vite — CLI — vite dev ve vite serve'in vite komutuna takma ad (alias) olduğunun kaynağı
• Vite — Migration from v7 — Vite 8'in Rolldown/Oxc geçişi, tarayıcı hedefi değişikliği, deprecated API'ler
• Vite — Features — CSS/CSS Modules importları, TypeScript transpile-only davranışı, isolatedModules zorunluluğu
• Vite — Env Variables and Modes — VITE_ önek kuralı, .env dosya öncelik sırası, yerleşik sabitler
• Vite — Why Vite — dependency pre-bundling ve native ESM servis modelinin nitel açıklaması
• Rolldown — Ana Sayfa — "Vite 8+'ı güçlendiren birleşik bundler" tanımı
• webpack — Concepts — Entry, Output, Loaders, Plugins, Mode, Browser Compatibility kavramları ve varsayılan değerler
• npm — vite paketi — güncel sürüm ve yayın tarihleri (8.3.0, 8.0.0)
• npm — @vitejs/plugin-legacy paketi — legacy tarayıcı eklentisinin güncel sürümü
• Vite — Release Notları (GitHub) — 8.3.0 bakım sürümü değişiklik listesi
• rolldown-vite — GitHub — ara-paketin arşivlenme notu
• webpack — npm registry — webpack'in güncel sürüm numarası ve yayın tarihi