Laravel Vite Tailwind build hatası, çoğu zaman tek bir paketten değil; Node sürümü, paket kilit dosyası, Vite giriş noktası, Tailwind sürümü ve production çıktısı arasındaki uyumsuzluktan oluşur. Yerelde çalışan tasarımın sunucuda kaybolması, npm run build komutunun modül bulamaması veya Laravel’in Vite manifest dosyasına erişememesi farklı katmanların kontrol edilmesini gerektirir.
Bu rehber, bağımlılıkları rastgele silip yeniden kurmak yerine hatayı katmanlara ayıran bir teşhis sırası sunar. Önce kullanılan Tailwind neslini ve Node ortamını belirleyeceğiz; ardından Vite girişlerini, CSS taramasını, Blade bağlantısını ve production deployment çıktısını doğrulayacağız.
Önce Tailwind ve Vite sürümünü belirleyin
Tailwind CSS v3 ile v4 kurulumlarını aynı projede karıştırmak, build sorunlarının yaygın nedenlerinden biridir. Güncel Tailwind Laravel–Vite kurulum rehberi v4 için @tailwindcss/vite eklentisini ve CSS dosyasında @import "tailwindcss"; kullanımını gösterir. Eski projelerde ise PostCSS, tailwind.config.js ve @tailwind direktifleri bulunabilir.
Önce mevcut projeyi olduğu sürümde çalıştırmaya odaklanın; hata çözerken aynı anda büyük Tailwind yükseltmesi yapmayın. Proje kökünde aşağıdaki komutlarla gerçek paket ağacını görün:
node -v
npm -v
npm ls vite laravel-vite-plugin tailwindcss @tailwindcss/vite
Kilit dosyasını paket yöneticisiyle eşleştirin
Repoda package-lock.json varsa npm, pnpm-lock.yaml varsa pnpm, yarn.lock varsa Yarn kullanın. Aynı projede birden fazla kilit dosyası bırakmak yerel ve CI ortamlarının farklı bağımlılık sürümleri kurmasına neden olabilir. CI veya production build sırasında npm kullanıyorsanız temiz ve tekrarlanabilir kurulum için çoğunlukla npm ci tercih edilir; bu komut mevcut lock dosyasıyla package.json uyuşmuyorsa hatayı görünür kılar.
Vite giriş dosyalarını ve Blade bağlantısını kontrol edin
Laravel’in resmî Vite dokümantasyonu, işlenecek CSS ve JavaScript girişlerinin vite.config.js içinde tanımlanmasını ve Blade şablonunda aynı yolların @vite direktifiyle çağrılmasını ister. Dosya adı veya büyük-küçük harf farkı, Windows’ta görünmeyip Linux build sunucusunda hata verebilir.
import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';
import tailwindcss from '@tailwindcss/vite';
export default defineConfig({
plugins: [
laravel({
input: [
'resources/css/app.css',
'resources/js/app.js',
],
refresh: true,
}),
tailwindcss(),
],
});Bu örnek Tailwind v4 yaklaşımı içindir. Projeniz v3 kullanıyorsa yalnızca hata çözmek amacıyla bu dosyayı aynen kopyalamayın. Önce package.json içindeki sürümü ve mevcut PostCSS yapılandırmasını doğrulayın.
<head>
@vite(['resources/css/app.css', 'resources/js/app.js'])
</head>CSS dosyasını JavaScript içinden import '../css/app.css'; ile yüklüyorsanız Blade tarafında yalnızca JavaScript girişini çağırabilirsiniz. Aynı dosyayı iki farklı girişten eklemek yerine tek bir yükleme stratejisi belirleyin. Blade bileşenlerinin düzeniyle ilgili sorunlar için Laravel Blade template rehberine başvurabilirsiniz.
Tailwind sınıfları neden build çıktısına girmiyor?
Build tamamlandığı hâlde sınıflar uygulanmıyorsa sorun Vite’tan çok Tailwind’in kaynak taramasında olabilir. Tailwind v4 Laravel rehberi, Blade ve JavaScript dosyalarının yanında framework tarafından üretilen görünümleri de @source ile tanımlar:
@import "tailwindcss";
@source "../../vendor/laravel/framework/src/Illuminate/Pagination/resources/views/*.blade.php";
@source "../../storage/framework/views/*.php";
@source "../**/*.blade.php";
@source "../**/*.js";Sınıf adlarını "bg-" + $color gibi parçalı ve dinamik üretmek tarayıcının değil, build aşamasındaki kaynak algılamanın sorunudur. Mümkün olduğunda sınıf adlarını kaynakta tam hâliyle bulundurun veya kullandığınız Tailwind sürümünün önerdiği açık kaynak tanımlama yöntemini uygulayın. Kullanıcı girdisini doğrudan CSS sınıfı olarak kabul etmeyin; izin verilen değerleri uygulama tarafında eşleyin.
Laravel Vite build hatasını adım adım teşhis edin
1. Temiz bağımlılık kurulumu yapın
npm ci
npm run buildnpm ci hata veriyorsa lock dosyasını sebepsiz yere silmek yerine package.json ile uyuşmazlığı inceleyin. Yerel geliştirmede bilinçli bir paket değişikliği yaptıysanız npm install ile lock dosyasını güncelleyip değişikliği sürüm kontrolünde birlikte değerlendirin.
2. İlk anlamlı build hatasını okuyun
Terminaldeki son satır her zaman kök neden değildir. İlk error, çözülemeyen import yolu veya dosya konumunu bulun. Vite’ın resmî sorun giderme rehberi, Linux’ta görülen “dosya bulunamadı” ve “modül bulunamadı” hatalarında import yolunun harf duyarlılığını kontrol etmeyi önerir. Components/Button.vue ile components/Button.vue aynı yol değildir.
3. Geliştirme ve production modunu ayırın
npm run dev geliştirme sunucusunu ve HMR bağlantısını kullanır; canlı sunucuda kalıcı çözüm değildir. Production için npm run build çalışmalı ve oluşan build dizini deployment paketinde bulunmalıdır. Sunucuda Node çalıştırılmıyorsa derlemeyi güvenilir CI ortamında üretip çıktıyı uygulama sürümüyle birlikte yayınlayın.
4. Laravel cache katmanlarını yenileyin
Blade veya config değişikliğinden sonra eski görünüm devam ediyorsa önce problemin frontend build mi yoksa Laravel cache mi olduğunu ayırın. Yapılandırma için Laravel config cache rehberindeki kontrollü akışı kullanın; tüm cache türlerini her hatada körlemesine temizlemeyin.
Production ortamında manifest hatası
Laravel production modunda @vite girişlerini derlenmiş manifest üzerinden çözer. public/build çıktısı yoksa, yanlış dizine üretildiyse veya yeni release’e kopyalanmadıysa sayfa asset adreslerini oluşturamaz. Kontrol sırası şöyledir:
- CI veya sunucuda
npm civenpm run buildbaşarıyla tamamlandı mı? public/builddizini ve manifest dosyası yeni release içinde var mı?vite.config.jsgirişleri ile Blade’deki@viteyolları aynı mı?- Özel build dizini tanımlandıysa Laravel ve Vite tarafında aynı ad mı kullanılıyor?
- CDN veya ters proxy eski hash’li asset adreslerini cache’liyor mu?
Derlemeyi deployment sürecinin parçası yapmak için GitHub Actions ile otomatik deployment rehberini inceleyin. Shared hosting üzerinde dizin yapısı ve Node kısıtları varsa Laravel shared hosting yayınlama rehberi ile document root ve release planını birlikte değerlendirin.
Kalıcı çözüm için kontrol listesi
- Tek paket yöneticisi ve tek kilit dosyası kullanın.
- Tailwind v3 ile v4 yapılandırma örneklerini karıştırmayın.
- Import yollarında büyük-küçük harf eşleşmesini kontrol edin.
- Vite girişleri, CSS importları ve Blade
@viteçağrılarını aynı yapıda tutun. - Production build çıktısını uygulama sürümüyle birlikte yayınlayın.
- Build başarılı olduktan sonra kritik sayfalarda CSS, JavaScript ve tarayıcı konsolunu smoke test ile doğrulayın.
- Çalışan sürümün build çıktısını rollback paketinde koruyun.
Sonuç
Laravel Vite Tailwind build hatasını kalıcı biçimde çözmek için önce sürüm ve paket yöneticisi uyumunu, sonra giriş dosyalarını ve Tailwind kaynak taramasını, son olarak production manifest çıktısını kontrol edin. Yerelde npm run dev çalışması production build’in doğru olduğu anlamına gelmez. Tekrarlanabilir bağımlılık kurulumu, CI build’i ve deployment sonrası asset testi aynı akışta bulunmalıdır.
Sık sorulan sorular
Laravel projesinde npm run dev ile npm run build farkı nedir?
npm run dev geliştirme sunucusu ve HMR için kullanılır. npm run build ise production ortamında sunulacak sürümlenmiş CSS, JavaScript ve manifest dosyalarını üretir.
Tailwind sınıfları neden production’da görünmüyor?
Kaynak tarama yolları Blade veya JavaScript dosyalarını kapsamıyor, sınıflar dinamik parçalarla üretiliyor ya da eski build dosyası yayınlanıyor olabilir. Tailwind sürümünüze uygun kaynak tanımını ve deployment çıktısını doğrulayın.
Vite manifest bulunamadı hatası nasıl çözülür?
npm run build komutunun başarıyla tamamlandığını, public/build çıktısının yeni release içinde bulunduğunu ve özel build dizini ayarlarının Laravel ile Vite tarafında eşleştiğini kontrol edin.
node_modules klasörünü silmek zorunlu mu?
Hayır. Önce hata mesajını ve paket ağacını inceleyin. Kilit dosyasına bağlı temiz kurulum gerekiyorsa npm ci kullanın; lock dosyasını sebepsiz silmek farklı paket sürümleri getirerek sorunu büyütebilir.
Tailwind v3 projesine v4 Vite eklentisi eklenmeli mi?
Yalnızca planlı bir yükseltme yapıyorsanız eklenmelidir. Mevcut v3 projede önce o sürümün yapılandırmasını düzeltin; hata çözümü ile büyük sürüm geçişini aynı değişiklikte birleştirmeyin.
