Vite 8 ile Anında Derleme Deneyimi

Derleme araçlarının en görünmez başarısı, varlığını unutturmasıdır. Kodu kaydettiğinizde tarayıcı, sayfayı kapatıp açmadan değişikliği gösteriyorsa, aradaki araç işini doğru yapmış demektir. Vite bu noktaya epey yaklaşmış durumda; ama bu hızın nereden geldiğini bilmek, onu doğru kullanmanın ilk adımı.

Bu metin, Vite'ın geliştirme sunucusunun neden hızlı olduğunu, üretim derlemesinin neden farklı çalıştığını ve bir Laravel projesinde bu iki dünyayı nasıl bağladığımızı anlatıyor. Örnekler bir Blade şablonuyla çalışan standart bir kurulumdan alındı; ayrıntılar sürüme göre değişebilir, bu yüzden her adımda resmi belgeleri de kontrol edin.

Yalnızca değişeni işlemek

Geleneksel paketleyiciler, bir değişiklik olduğunda uygulamanın büyük bir bölümünü yeniden derlemek zorunda kalırdı. Proje büyüdükçe bu bekleme dakikalara çıkabiliyordu. Vite'ın yaklaşımı farklıdır: geliştirme sırasında tarayıcı, kaynakları modül olarak doğrudan ister ve sunucu her modülü yalnızca istendiğinde hazırlar.

Bunun sonucu, bir CSS değişikliğinin sayfa durumunu kaybetmeden uygulanmasıdır. Bir form yarıda kalmış, bir modal açık ve siz bir rengi değiştirdiğinizde, o modal açık kalır. Bu davranışa sıcak modül değiştirme (HMR) denir.

Hızlı geri bildirim, deneyselliğin ön koşuludur.

Bağımlılıkların ön paketlenmesi

Uygulama kodunuz sık değişirken, bağımlılıkların çoğu değişmez. Vite bu farkı kullanır: node_modules içindeki kütüphaneleri ilk çalıştırmada önceden paketler ve tarayıcıya tek parça hâlinde sunar. Böylece bir sayfa, yüzlerce küçük dosya yerine birkaç büyük paketle açılır.

Bu adım, bir kütüphane eklediğinizde ya da sürümünü değiştirdiğinizde sunucunun yeniden başlatılmasını gerektirebilir. Garip bir hata görüyorsanız, önbelleği temizleyip sunucuyu yeniden başlatmak çoğu zaman yeterlidir.

Geliştirme ve üretim: iki ayrı dünya

Geliştirme sunucusu, kodu olduğu gibi tarayıcıya servis eder. Üretimde ise tarayıcının kaç dosya istediği ve ne kadar büyük paketler indirdiği önemlidir. Bu yüzden üretim derlemesi kodu küçültür, ağaç sallama ile kullanılmayan kodu ayıklar ve dosya adlarına içerik özeti ekler.

İçerik özetli dosya adları, uzun süreli önbellekleme stratejisini güvenle mümkün kılar. Dosya içeriği değişmedikçe adı aynı kalır ve tarayıcı onu yeniden indirmez. İçerik değiştiğinde ad da değiştiği için eski önbellek kendiliğinden geçersiz olur.

Laravel ile bağlantı

Laravel, Vite ile resmi bir eklenti üzerinden çalışır. Bu eklenti, Blade şablonlarında @vite direktifini sağlar ve üretim derlemesindeki dosya adlarını bir manifest dosyasından okur.

// vite.config.js
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(),
    ],
});

Blade tarafında ise giriş noktaları tek bir satırla eklenir:

<head>
    @vite(['resources/css/app.css', 'resources/js/app.js'])
</head>

refresh: true ayarı, Blade dosyalarında yapılan değişikliklerde tarayıcının sayfayı yeniden yüklemesini sağlar. Bu, sunucu tarafı şablonla çalışan bir projede özellikle yararlıdır, çünkü HMR yalnızca JavaScript ve CSS için geçerlidir.

"Unable to locate file in Vite manifest" hatası

Bu hata, Laravel tarafında en sık karşılaşılan Vite sorunudur. Sayfa, üretim modunda bir dosya istiyor ama manifest dosyasında bu dosya yok. Nedeni çoğu zaman basittir: npm run build çalıştırılmamıştır ya da derleme eski bir yapılandırmayla yapılmıştır.

1. Geliştirme sunucusunu çalıştırıyorsanız npm run dev açık olmalıdır.
2. Üretim modunda çalışacaksanız npm run build komutunu çalıştırın.
3. public/build/manifest.json dosyasının varlığını kontrol edin.
4. Giriş noktası yolunun vite.config.js içindeki input listesiyle eşleştiğinden emin olun.

Bu hatayı görmek bir hata değil, bir sinyaldir: uygulama, derlenmiş bir varlık bekliyor ama onu bulamıyor. Derlemeyi tekrar çalıştırmak genellikle sorunu çözer.

Derleme ortamını tutarlı tutmak

Geliştirme ile üretim arasındaki en sinsi fark, ortam değişkenlerinde ve Node sürümünde yaşanır. Yerel makinede çalışan bir derleme, sunucuda farklı bir Node sürümüyle farklı sonuç verebilir. Bu yüzden projede bir Node sürümü belirtmek ve derlemeyi dağıtım sırasında yeniden yapmak, öngörülemeyen hataları azaltır.

• Node sürümünü .nvmrc ya da package.json içindeki engines alanıyla sabitleyin.
• Derlemeyi her dağıtımda yeniden yapın; public/build klasörünü kaynak kontrolüne eklemeyin.
• Ortam değişkenlerinin derleme sırasında gerekli olup olmadığını kontrol edin.

Performans: hız nerede kaybolur?

Vite geliştirme sunucusu çok hızlıdır, ama uygulama yavaşsa sorun büyük olasılıkla başka bir yerdedir. Büyük bir JavaScript paketi, gereksiz yere yüklenen kütüphaneler ya da render sırasında yapılan ağır DOM işlemleri, derleyicinin hızından bağımsız olarak kullanıcıyı bekletir.

Derleme çıktısını incelemek bu nedenle önemlidir. Hangi paketin ne kadar yer kapladığını görmek, gereksiz bağımlılığı fark etmenizi sağlar. Bir kütüphane yalnızca tek bir yerde kullanılıyorsa, onu o sayfaya özgü bir giriş noktasına taşımak paketi küçültebilir.

npm run build -- --mode production
ls -lh public/build/assets

Dosya boyutlarına bakmak basit bir alışkanlıktır, ama kararlar için yeterlidir. Birkaç yüz kilobayt fark eden bir kütüphane, mobil kullanıcılarda ilk boyamayı belirgin biçimde geciktirir.

Üretim derlemesi neden farklı davranır?

Geliştirme sırasında her şey çalışıyor gibi görünebilir, ama üretimde bir hata çıkabilir. Bunun sık nedeni, geliştirme sunucusunun bazı kuralları gevşek uygulamasıdır. Örneğin tree-shaking, ayrı bir modül yüklemesi ya da CSS sıralaması üretimde farklı sonuç verebilir.

Geliştirme ortamı bir vaat, üretim derlemesi ise kanıttır.

Bu nedenle bir değişikliği yayına almadan önce üretim derlemesini yerelde çalıştırıp sayfayı test etmek iyi bir alışkanlıktır. Derleme çıktısını yerelde açıp en önemli üç sayfayı kontrol etmek, birçok sürprizi önler.

Ortam değişkenleri ve istemci tarafı

Vite'ta ortam değişkenleri, tarayıcıya yalnızca belirli bir önekle başlayan değerler olarak ulaşır. Bu önek varsayılan olarak VITE_'dır. Önek taşımayan bir değişken, derleme sırasında istemci koduna girmez; bu bir güvenlik özelliğidir.

# .env
VITE_APP_NAME="Pusula"
DB_PASSWORD=gizli-deger   # tarayıcıya asla çıkmaz

// resources/js/app.js
console.log(import.meta.env.VITE_APP_NAME);

Bu kuralın bir sonucu olarak, VITE_ ile başlayan her değişkenin herkese açık olduğu varsayılmalıdır. Gizli bir anahtarı bu önekle tanımlamak, onu sayfa kaynağına koymak demektir. Gizli bilgiler yalnızca sunucu tarafında kalmalıdır.

Public klasörü ve varlık yolları

Varlıkları iki farklı biçimde kullanabilirsiniz. resources altındaki bir dosyayı JavaScript veya CSS içinde içe aktarırsanız, Vite onu adlandırır, derler ve içerik özeti ekler. public altındaki bir dosya ise olduğu gibi servis edilir ve adı değişmez.

Büyük ve sık değişmeyen görseller için public klasörü pratik bir seçimdir. Ama bu görseller uzun süreli önbelleğe alınamaz; ada dayalı bir sürümleme yoksa, güncellenen bir görsel tarayıcıda eski kalabilir. Bu tür dosyalar için adlarına bir sürüm eklemek, bu sorunu ortadan kaldırır.

Önbellek ve tarayıcıda eski sürüm

Yeni bir dağıtımdan sonra sayfa bozuk görünüyorsa, sorun çoğu zaman tarayıcının eski bir manifest dosyasını ya da eski bir JavaScript dosyasını tutmasıdır. Sert yenileme bu sorunu çözer, ama kullanıcıların bunu bilmesini beklemek gerçekçi değildir.

1. Derlemenin yeni dosyalar ürettiğini ve manifest.json dosyasının güncellendiğini kontrol edin.
2. Laravel tarafında görünüm önbelleğini temizleyin: php artisan view:clear.
3. Yapılandırma önbelleğini de gerekiyorsa temizleyin: php artisan config:clear.
4. Tarayıcıda yeni sekmeyle deneyin; hâlâ eski görünüyorsa önbelleği manuel temizleyin.

Bu adımlar bir dağıtım sonrası kontrol listesine dönüştürülebilir. Böylece sorun ortaya çıktığında, kimin ne yapacağı baştan bellidir ve kullanıcılar bozuk bir sayfayla karşılaşmaz.

Tailwind ile birlikte derleme

Tailwind 4 ile birlikte Vite kullanıldığında, sınıfların taranması ve üretilmesi bir eklenti üzerinden yapılır. Bu eklenti, projedeki Blade şablonlarını ve JavaScript dosyalarını tarar, kullanılan sınıfları üretir. Kullanılmayan sınıflar çıktıya girmez, bu da CSS dosyasını küçük tutar.

/* resources/css/app.css */
@import "tailwindcss";

@source "../views";
@source "../js";

Bir sınıf, bir Blade dosyasında yalnızca bir dizgi olarak geçiyorsa, tarayıcı bunu tanır ve üretilir. Ama bir sınıf, dinamik bir birleşimle oluşturuluyorsa ('text-' + renk gibi) tarayıcı bunu göremez ve sınıf çıktıya girmez. Bu tür durumlarda sınıf adlarının tam hâlinin dosyada yazılı olması gerekir.

Derleme süresi ve çıktı boyutunu izlemek

Derleme hızı, bir ekip için bir ölçüdür. Yeni bir kütüphane eklendiğinde ya da bir sayfa büyüdüğünde derleme süresi artabilir. Bu artışı fark etmek için, derleme süresini ve çıktı boyutunu düzenli olarak not etmek yeterlidir.

• Derleme süresi, bir haftada önemli ölçüde artıyorsa, son eklenen bağımlılığı inceleyin.
• Çıktı boyutunda ani bir sıçrama varsa, bir kütüphanenin tamamının içe aktarılıp aktarılmadığına bakın.
• Geliştirme sunucusunun yeniden başlatılma süresi uzuyorsa, önbelleklenen bağımlılıkları kontrol edin.

Paylaşılan yapılandırma

Her geliştiricinin kendi derleme yapılandırmasını kullanması, "bende çalışıyor" sorununun ana kaynağıdır. Yapılandırma dosyası depoda tutulmalı ve kişisel değişiklikler yalnızca ortam değişkenleriyle yapılmalıdır. Bu sayede herkes aynı derlemeyi, aynı sonuçlarla elde eder.

Ekip bir eklenti eklemek istediğinde, bunu yapılandırma dosyasında bir değişiklikle önermesi ve diğerlerinin gözden geçirmesi yeterlidir. Böylece derleme davranışı yavaş yavaş değil, bilinçli olarak değişir.

Sonuç

Vite'ın hızı, yalnızca değişeni işlemekten, bağımlılıkları önceden paketlemekten ve tarayıcıya modül olarak servis etmekten gelir. Üretimde ise aynı araç, dosyaları küçültür ve önbelleğe uygun adlarla çıkarır. Bu iki dünyayı bağlayan şey doğru yapılandırma ve derlemeyi tutarlı tutmaktır.

Projenizi bu hıza hazırlamak için kısa bir liste:

1. Node sürümünü sabitleyin ve derlemeyi her dağıtımda yeniden yapın.
2. @vite giriş noktalarını ve input listesini aynı dosyaları gösterecek şekilde tutun.
3. Derleme çıktısındaki büyük paketleri düzenli olarak inceleyin.
4. Yayına almadan önce üretim derlemesini yerelde çalıştırıp kontrol edin.