Modern bir Laravel projesi açtığında karşına çıkan vite.config.js dosyası ilk başta kafa karıştırıcı olabilir; işte Vite Laravel ikilisinin tam olarak ne yaptığını, geliştirme sırasında neden tarayıcının anında güncellendiğini ve üretime çıkarken o gizemli manifest.json dosyasının neye yaradığını bu yazıda baştan sona açıyorum. Laravel 9.19'dan bu yana varsayılan derleme aracı Webpack tabanlı Laravel Mix değil, Vite. Mantığı bir kez oturttuğunda CSS ve JavaScript varlıklarını yönetmek çok daha keyifli hâle geliyor.
Vite nedir ve neden Laravel'in varsayılanı oldu
Vite, Vue'nun da yaratıcısı olan Evan You tarafından geliştirilen bir frontend derleme aracı. İki ayrı işi tek araçta birleştirir: geliştirme sırasında çok hızlı bir geliştirme sunucusu, üretim için ise Rollup tabanlı optimize edilmiş bir paketleyici (bundler). Eski araçlardan farkı, geliştirme modunda kodunu en baştan büyük bir paket hâline getirmemesi. Bunun yerine tarayıcının yerel ES modülleri desteğinden yararlanır ve dosyaları yalnızca istendikçe servis eder. Sonuç: projenin boyutu büyüse bile geliştirme sunucusu neredeyse anında açılır.
Laravel ile entegrasyonu laravel-vite-plugin paketi sağlar. Bu eklenti, hangi dosyaların giriş noktası (entry point) olduğunu Vite'a bildirir ve Blade tarafında kullanacağın @vite direktifiyle konuşur.
Kurulum ve temel yapılandırma
Yeni bir Laravel projesinde Vite zaten gelir. Bağımlılıkları kurmak ve geliştirme sunucusunu başlatmak için iki komut yeterli:
npm install
npm run devProje kökündeki vite.config.js dosyası giriş noktalarını tanımlar:
import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';
export default defineConfig({
plugins: [
laravel({
input: ['resources/css/app.css', 'resources/js/app.js'],
refresh: true,
}),
],
});Burada input dizisi, Vite'ın takip edeceği ana dosyaları belirtir. refresh: true seçeneği ise Blade şablonlarını, route dosyalarını veya başka PHP kaynaklarını her kaydettiğinde tarayıcıyı otomatik yeniler. Blade tarafında varlıkları sayfaya şu şekilde dâhil edersin:
<!DOCTYPE html>
<html>
<head>
@vite(['resources/css/app.css', 'resources/js/app.js'])
</head>@vite direktifi sihirli kısım: ortama göre davranışını değiştirir. Geliştirmede Vite sunucusuna işaret eder, üretimde ise derlenmiş dosyalara.
Geliştirmede HMR: tarayıcı neden anında güncelleniyor
HMR (Hot Module Replacement), bir dosyayı kaydettiğinde sayfanın tamamını yeniden yüklemeden yalnızca değişen modülü tarayıcıya enjekte eden mekanizmadır. npm run dev çalıştığında Vite, varsayılan olarak 5173 portunda bir geliştirme sunucusu açar. Bu sırada projenin kökünde public/hot adında küçük bir dosya oluşur; içinde geliştirme sunucusunun adresi yazar.
@vite direktifi her sayfa render edildiğinde önce bu public/hot dosyasının var olup olmadığına bakar. Varsa, varlıkları kendi sunmaz; bunun yerine etiketleri Vite sunucusuna yönlendirir ve bir WebSocket bağlantısı kurulur. Bir CSS dosyasını değiştirdiğinde sayfa hiç yenilenmeden stil güncellenir; tek bir JavaScript modülünü düzenlediğinde de yalnızca o modül değişir. Bu, özellikle uygulama durumunu (form girdileri, açık modallar) koruduğu için geliştirme akışını çok hızlandırır.
- Tam yenileme yok: sadece değişen modül güncellenir, sayfa durumu korunur.
- Anlık geri bildirim: kaydet tuşuna bastığın an değişikliği görürsün.
- Otomatik enjeksiyon: yeni eklediğin
importbağımlılıkları anında çözülür.
Üretimde bundling ve manifest mantığı
Siteyi yayına alacağın zaman npm run build komutunu çalıştırırsın. Vite bu aşamada Rollup'ı kullanarak tüm modülleri birleştirir, ölü kodu temizler (tree-shaking), JavaScript ve CSS'i küçültür (minify) ve dosya adlarına içerik tabanlı bir özet (hash) ekler. Çıktı public/build klasörüne yazılır.
İşte o hash kritik: app.js yerine app-4ed1f8c2.js gibi bir isim üretilir. Dosyanın içeriği her değiştiğinde hash de değişir. Böylece tarayıcının ve CDN'in eski sürümü önbellekten servis etme sorunu (cache busting) kökten çözülür. Ama Blade şablonunda bu rastgele hash'i elle yazamazsın. İşte burada manifest devreye girer.
Build sonunda Vite, public/build/.vite/manifest.json dosyasını üretir. Bu dosya, kaynak dosya adlarını derlenmiş çıktılarla eşler. Basitleştirilmiş bir örnek şöyle görünür:
{
"resources/js/app.js": {
"file": "assets/app-4ed1f8c2.js",
"isEntry": true,
"css": ["assets/app-1b2c3d4e.css"]
}
}Üretim ortamında @vite(['resources/js/app.js']) direktifi public/hot dosyasını bulamaz, dolayısıyla manifest'i okur. Kaynak yolundan gerçek hash'li dosya adını bulur ve doğru <script> ile <link> etiketlerini üretir. Sen kaynak yolunu yazarsın, Laravel manifest üzerinden doğru fiziksel dosyayı çözer. Bu yüzden public/build klasörünün sunucuya mutlaka deploy edilmesi gerekir.
Sık karşılaşılan sorunlar ve çözümleri
Vite Laravel kurulumunda en sık görülen hata, üretimde "Unable to locate file in Vite manifest" mesajıdır. Bu neredeyse her zaman npm run build komutunun çalıştırılmamış olmasından ya da public/build klasörünün sunucuda eksik olmasından kaynaklanır. Birkaç pratik nokta:
- Deploy'da build et: sunucuya çıkmadan önce mutlaka
npm run buildçalıştır vepublic/buildklasörünü gönder. public/hotdosyasını commit'leme:npm run devsonrası bu dosya kalırsa üretim hatalı şekilde geliştirme sunucusunu aramaya devam eder. GeliştirmeyiCtrl+Cile düzgün kapat.- Statik varlıklar için
Vite::asset(): resim gibi dosyalara işaret etmek içinresources/içine koyup yardımcı fonksiyonu kullan ya da public klasörünü doğrudan kullan. - SSL/proxy arkasında: Docker veya uzak bir geliştirme ortamında HMR bağlantısı kurulamıyorsa
vite.config.jsiçindekiserver.hmrayarlarını host'a göre düzenlemen gerekebilir.
Sık Sorulan Sorular
Vite ile Laravel Mix arasındaki fark nedir?
Laravel Mix, Webpack üzerine kurulu bir sarmalayıcıydı ve geliştirmede tüm paketi baştan derlediği için yavaştı. Vite ise geliştirmede yerel ES modüllerini kullanarak anında açılır, üretimde Rollup ile optimize eder. Laravel 9.19'dan itibaren yeni projelerin varsayılanı Vite'tır; Mix hâlâ desteklenir ama yeni projeler için Vite önerilir.
public/build klasörünü Git'e eklemeli miyim?
Genelde hayır. Bu klasör derlenmiş çıktıdır ve genellikle .gitignore'a eklenir; bunun yerine deploy adımında npm run build çalıştırılır. Ancak build adımını çalıştıramayacağın paylaşımlı bir hosting kullanıyorsan, klasörü commit'leyip doğrudan göndermek de geçerli bir stratejidir.
Geliştirmede npm run dev ile php artisan serve aynı anda mı çalışmalı?
Evet. php artisan serve (veya senin web sunucun) PHP uygulamasını sunar; npm run dev ise ayrı bir terminalde Vite sunucusunu açar ve HMR'yi sağlar. İkisi birlikte çalışınca Blade sayfaları varlıkları Vite sunucusundan çeker.
Frontend derleme süreciniz mi yavaşlıyor ya da Vite manifest hataları mı alıyorsunuz? Laravel projelerinde asset pipeline kurulumu, deploy otomasyonu ve performans için size yardımcı olabilirim. Benimle iletişime geçin ve projenizi konuşalım.