Vite ile React Kurulumu

01Vite Nedir, Neden Tercih Edilir?

Vite, modern web projeleri için geliştirilmiş bir derleme aracı ve geliştirme sunucusudur. Geliştirme sırasında kodu tarayıcının yerel ES modül desteğiyle sunar, yalnızca istenen dosyayı işler. Bu yüzden proje büyüse bile sunucu saniyeler içinde açılır ve kaydettiğiniz değişiklik sayfayı yenilemeden ekrana yansır.

Yayın aşamasında ise Vite kodunuzu küçültülmüş, parçalara ayrılmış ve önbelleğe uygun dosya adlarıyla paketler. React, Vue, Svelte gibi kütüphaneler için hazır şablonlar sunar; React ekosisteminde en yaygın başlangıç noktalarından biri haline gelmiştir.

Create React App Alternatifi Olarak Vite

Uzun yıllar React projeleri Create React App ile başlatıldı. React ekibi artık bu aracı yeni projeler için önermiyor; resmi dokümantasyon ya bir çatı (Next.js gibi) ya da Vite gibi bir derleme aracıyla başlamayı öneriyor. Create React App alternatifi arıyorsanız Vite, en az yapılandırmayla en hızlı geçiş yoludur.

Sunucu tarafında sayfa üretimi, dosya tabanlı yönlendirme ve SEO için hazır sayfa çıktısı gerekiyorsa Next.js kurulumu rehberimize bakın. Yönetim paneli, iç araç ya da tek sayfa uygulama (SPA) için Vite genellikle daha sade bir tercihtir.

02Önkoşullar

Vite'ın tek gerçek önkoşulu Node.js'tir. Vite yeni sürümlerinde eski Node sürümlerini desteklemeyi bırakır; bu nedenle nodejs.org üzerindeki güncel LTS sürümünü kurmak en güvenli yoldur. npm, Node.js ile birlikte gelir.

• Node.js güncel LTS sürümü ve onunla gelen npm.
• Bir kod editörü; kurulum ve önerilen eklentiler için VS Code kurulumu yazısına göz atabilirsiniz.
• Terminal: Windows'ta PowerShell ya da Windows Terminal, macOS'ta Terminal, Linux'ta tercih ettiğiniz kabuk.
• İsteğe bağlı: sürüm kontrolü için Git.

03İşletim Sistemine Göre Node.js

Node.js'i nodejs.org üzerinden indirip kurabilirsiniz. Birden fazla projede farklı Node sürümleri kullanacaksanız bir sürüm yöneticisi tercih etmek ileride işinizi kolaylaştırır.

Windows

nodejs.org'dan LTS kurulum dosyasını indirip varsayılan seçeneklerle kurun ya da PowerShell'de winget kullanın. Kurulumdan sonra terminali kapatıp yeniden açın ki PATH güncellensin.

winget install OpenJS.NodeJS.LTS
node -v
npm -v

macOS

Resmi kurulum paketini kullanabilir ya da Homebrew yüklüyse tek komutla kurabilirsiniz.

brew install node
node -v
npm -v

Linux

Dağıtım depolarındaki Node sürümü çoğu zaman eskidir. nvm ile kullanıcı düzeyinde kurmak hem güncel sürüm verir hem de sudo ihtiyacını ortadan kaldırır; nvm'i kendi GitHub sayfasındaki kurulum betiğiyle yükledikten sonra şu komutları çalıştırın.

nvm install --lts
nvm use --lts
node -v

04React Proje Oluşturma Adımları

Node.js hazırsa React proje oluşturma işlemi tüm işletim sistemlerinde aynıdır. Komut sizi etkileşimli olarak yönlendirir: proje adı, çatı (React) ve varyant (TypeScript) sorulur. Şablonu doğrudan komutta belirtmek isterseniz aşağıdaki biçimi kullanın; npm'de ek parametreler iki tireden sonra yazılır.

• JavaScript ile çalışmak isterseniz şablon adı react, TypeScript için react-ts olur.
• Terminalde Local satırında görünen adresi (varsayılan localhost:5173) tarayıcıda açın.
• src/App.tsx dosyasında bir metni değiştirip kaydedin; sayfa yenilenmeden güncellenirse HMR (anlık modül değişimi) çalışıyor demektir.

npm create vite@latest benim-uygulamam -- --template react-ts
cd benim-uygulamam
npm install
npm run dev

pnpm create vite benim-uygulamam --template react-ts
yarn create vite benim-uygulamam --template react-ts

05Proje Yapısını Tanıyın

Vite projesinde ilk dikkat çeken fark, index.html dosyasının kök dizinde durmasıdır. Vite bu dosyayı giriş noktası olarak kullanır ve içindeki script etiketi src/main.tsx dosyasını çağırır.

Ortam Değişkenleri

Vite yalnızca VITE_ önekiyle başlayan değişkenleri istemci koduna aktarır ve bunlara import.meta.env üzerinden erişirsiniz. Bu değişkenler tarayıcıya giden pakete gömülür; API gizli anahtarı gibi bilgileri asla buraya koymayın, sunucu tarafında saklayın.

VITE_API_URL=https://api.ornek.com

06Build Alma ve Yayına Çıkma

Geliştirme sunucusu yalnızca yerel çalışma içindir. Yayına alacağınız sürümü npm run build ile üretirsiniz; çıktı dist klasörüne yazılır. npm run preview, bu çıktıyı yerelde gerçek yayına yakın biçimde test etmenizi sağlar.

dist klasörü düz HTML, CSS ve JavaScript dosyalarından oluşur; herhangi bir statik barındırma ortamına ya da Nginx gibi bir web sunucusuna yüklenebilir. Hız açısından dosyaların sıkıştırılması ve uzun süreli önbellek başlıklarıyla sunulması önemlidir; bu ayarların ayrıntısını hız ve performans yönetimi sayfamızda anlatıyoruz.

• Uygulama alt klasörde yayınlanacaksa (ornek.com/panel/) vite.config.ts içinde base seçeneğini o yola ayarlayın.
• React Router kullanıyorsanız sunucuda tüm bilinmeyen adresleri index.html'e yönlendiren bir kural ekleyin.
• Arama motorlarında görünmesi gereken içerik sayfalarında yalnız istemci tarafı çizim yetersiz kalabilir; bu noktada SEO uyumlu web tasarımı yaklaşımı önem kazanır.

npm run build
npm run preview

07Sık Hatalar ve Çözümleri

Vite kurulumunda karşılaşılan hataların büyük kısmı Node sürümü, port ya da yayın ayarlarından kaynaklanır. Aşağıdaki tablo en sık durumları özetler; daha fazla komut için npm komutları rehberine bakabilirsiniz.

08Sonraki Adımlar

Çalışan bir proje elde ettikten sonra yönlendirme için React Router, veri çekme için TanStack Query, stil için Tailwind CSS ya da CSS Modules gibi araçları ekleyebilirsiniz. Kod kalitesi için şablonla gelen ESLint ayarlarını projenize göre genişletin.

Vite ve React ikilisi; rezervasyon paneli, stok ekranı, randevu takibi ya da QR menü yönetimi gibi iş uygulamaları için güçlü bir temel sunar. Bu tür ürünlerde arayüz kadar veri modeli, yetkilendirme ve yedekleme de belirleyicidir; hazır bir altyapı üzerinde ilerlemek isterseniz sektöre özel yazılım çözümleri zaman kazandırabilir.

Teknik altyapı kadar arayüz kurgusu da önemlidir: bileşenleri yazmadan önce kullanıcı akışını ve ekran düzenini planlamak, UI/UX tasarım sürecinin temelidir. Mobil kırılımları en baştan düşünmek de mobil uyumlu tasarım açısından sonradan düzeltmekten çok daha ucuzdur.