Windows VPS’e React.js Nasıl Kurulur: Eksiksiz Kurulum Kılavuzu

React.js, Meta (eski adıyla Facebook) tarafından sürdürülen, bileşen tabanlı kullanıcı arayüzleri oluşturmak için kullanılan açık kaynaklı bir JavaScript kütüphanesidir; özellikle tam sayfa yeniden yüklemesi olmadan DOM’u dinamik olarak güncelleyen tek sayfalı uygulamalar (SPA’lar) için tasarlanmıştır. React’i yerel bir iş istasyonu yerine bir Windows VPS üzerine kurmak, kalıcı ve uzaktan erişilebilir bir geliştirme ortamı sağlar; bu da ekip iş birliği, CI/CD süreçleri ve hazırlık ortamı dağıtımları için idealdir.

Bu kılavuz, bir Windows VPS üzerinde üretim kalitesinde React.js kurulumunun her adımını ele almaktadır: Node.js çalışma zamanı yapılandırması ve ortam değişkeni yönetiminden proje iskeleti oluşturma, geliştirme sunucusu işletimi ve üretim derleme çıktısına kadar. Ayrıca, yüzeysel düzeydeki eğitimleri takip eden mühendislerin sıklıkla karşılaştığı, göz ardı edilen hata senaryolarını da kapsamaktadır.

React’i Localhost Yerine Windows VPS’e Neden Kurmalısınız?

React geliştirme ortamınızı yerel bir makine yerine bir VPS Hosting örneği üzerinde çalıştırmak, gerçek dünyada karşılaşılan çeşitli sorunları çözer:

• Kalıcı çalışma süresi: Yerel makineniz kapalı olsa bile geliştirme sunucusu çalışmaya devam eder; bu sayede uzaktaki ekip üyeleri veya QA test uzmanları her zaman canlı önizleme URL’sine erişebilir.
• Tutarlı ortam: Her geliştirici aynı işletim sistemine, Node sürümüne ve bağımlılık ağacına bağlanır; böylece “bende çalışıyor” hataları ortadan kalkar.
• Kaynak izolasyonu: CPU yoğun derlemeler (npm run build, büyük Webpack derlemeleri) yerel iş istasyonunuzun performansını düşürmez.
• Hazırlık ortamı uyumu: Üretim altyapınız da Windows Server tabanlıysa (IIS, ASP.NET hibrit mimarileri), bir Windows VPS hedef dağıtım ortamını birebir yansıtır.
• Uzaktan erişilebilirlik: Geliştirme sunucusunu belirli bir port üzerinden açığa çıkarabilir ve herhangi bir tarayıcıdan, her yerden erişebilirsiniz.

İş yükünüz zamanla derlenmiş React varlıklarını bir Node.js API’siyle birlikte sunacak ölçeğe ulaşırsa, garantili I/O verimliliği ve gürültülü komşu etkisi olmaksızın çalışmak için Dedicated Servers ortamına geçmeyi değerlendirin.

Ön Koşullar

Başlamadan önce, Windows VPS’inizde aşağıdakilerin mevcut olduğunu doğrulayın:

• Windows Server 2016 / 2019 / 2022 veya Windows 10/11 (64-bit)
• RDP üzerinden Yönetici veya yükseltilmiş kullanıcı erişimi
• VPS’te Giden internet erişimi (yükleyicileri ve npm paketlerini indirmek için)
• En az 2 GB RAM — Webpack’in bellek içi derlemesi çok fazla bellek tüketir; birden fazla bağımlılığa sahip projeler için 4 GB önerilir
• Bir metin editörü veya IDE — Visual Studio Code, React geliştirme için fiili standarttır

Adım 1: Windows’a Node.js Kurulumu

1.1 LTS Sürümünü İndirin

React, Node.js’in en son sürümünü gerektirmez. Kararlılığın önemli olduğu her ortam için LTS (Uzun Vadeli Destek) kanalı doğru seçimdir.

1. VPS’inizde bir tarayıcı açın (veya uzaktan indirip RDP panosu aracılığıyla aktarın).
2. https://nodejs.org adresine gidin.
3. Güncel LTS sürümü (örn. 20.x veya 22.x) için Windows Installer (.msi) dosyasını indirin.

Önemli not: Her zaman .msi arşivi değil, 64-bit .zip yükleyicisini indirin. .msi, PATH kaydını, servis entegrasyonunu ve Visual C++ Redistributable bağımlılığını otomatik olarak yönetir. .zip arşivi manuel PATH yapılandırması gerektirir ve npm‘ın tanınmaması hatalarının yaygın bir kaynağıdır.

1.2 Yükleyiciyi Çalıştırın

İndirilen .msi dosyasını çalıştırın ve sihirbazı takip edin:

1. Lisans sözleşmesini kabul edin.
2. Özel bir nedeniniz yoksa hedef yolu varsayılan olarak bırakın (C:Program Filesnodejs).
3. Özel Kurulum ekranında aşağıdaki bileşenlerin tümünün işaretli olduğundan emin olun:

• Node.js runtime
• npm package manager
• PATH’e Ekle (bu en önemli onay kutusudur — işaretlenmezse hiçbir terminal node veya npm‘ı tanımaz)
• Çevrimiçi belge kısayolları (isteğe bağlı)

1. Yerel Modüller için Araçlar ekranında, yerel derleme gerektiren npm paketleri (node-gyp, bcrypt, sharp vb.) kullanmayı planlıyorsanız “Gerekli araçları otomatik olarak yükle” seçeneğini işaretleyin. Bu seçenek Chocolatey, Python ve Visual Studio Build Tools’u sessizce yükler.
2. Kurulumu tamamlayın ve terminal oturumunu yeniden başlatın (PATH değişiklikleri hemen yansımıyorsa RDP oturumunun tamamını yeniden başlatın).

1.3 Kurulumu Doğrulayın

Yeni bir PowerShell veya Komut İstemi penceresi açın (kurulumdan önce açık olan bir pencere değil — güncellenmiş PATH’e sahip olmayacaktır) ve şunu çalıştırın:

node -v

npm -v

Her iki komut da sürüm dizesi döndürmelidir. Herhangi biri 'node' is not recognized as an internal or external command döndürüyorsa PATH doğru ayarlanmamış demektir. Aşağıdaki sorun giderme bölümüne bakın.

Beklenen çıktı örneği:

v20.14.0
10.7.0

1.4 npm’nin Global Paket Dizinini Yapılandırın (İsteğe Bağlı ama Önerilir)

Varsayılan olarak npm, global paketleri C:Users<username>AppDataRoamingnpm dizinine yükler. Paylaşımlı veya çok kullanıcılı bir Windows Server ortamında bu durum izin çakışmalarına yol açabilir. Özel bir global dizin ayarlamak için:

npm config set prefix "C:npm-global"

Ardından C:npm-global‘ı Sistem Özellikleri > Ortam Değişkenleri > Sistem Değişkenleri > Path üzerinden sistem PATH’inize ekleyin.

Adım 2: React Uygulaması İskeleti Oluşturma

2.1 Modern Yaklaşım: Vite (Create React App Yerine Önerilir)

Orijinal makale create-react-app (CRA) kullanımını önermektedir. Bu güncel olmayan bir tavsiyedir. CRA, 2023’ün başında resmi olarak kullanımdan kaldırılmış ve React çekirdek ekibi tarafından artık sürdürülmemektedir. React belgelerinin kendisi de yeni projeler için artık CRA’yı önermemektedir.

Güncel önerilen iskelet araçları şunlardır:

Bir Windows VPS üzerinde basit bir SPA için 2024 ve sonrasında doğru seçim Vite‘tır.

2.2 Vite ile Yeni Bir React Projesi Oluşturma

PowerShell’i açın ve projeler dizininize gidin:

cd C:Projects

Yeni bir React projesi iskeleti oluşturun:

npm create vite@latest my-react-app -- --template react

TypeScript kullanmak için (önemsiz olmayan herhangi bir proje için güçlü biçimde önerilir):

npm create vite@latest my-react-app -- --template react-ts

Proje dizinine gidin ve bağımlılıkları yükleyin:

cd my-react-app
npm install

2.3 Create React App Kullanmanız Gerekiyorsa (Eski Projeler)

Global kurulum yapmadan çalıştırmak için npx kullanın:

npx create-react-app my-react-app

npm install -g create-react-app çalıştırmayın. Global kurulum yaklaşımı kullanımdan kaldırılmıştır ve güncel olmayan önbelleğe alınmış bir sürümü çekecektir. npx kullanmak her zaman kayıt defterinden mevcut en son sürümü getirir.

Adım 3: Geliştirme Sunucusunu Çalıştırma

3.1 Geliştirme Sunucusunu Başlatma

Vite tabanlı bir proje için:

npm run dev

CRA tabanlı bir proje için:

npm start

Her iki komut da yerel bir geliştirme sunucusu başlatır. Vite varsayılan olarak http://localhost:5173; CRA ise http://localhost:3000 portunu kullanır.

3.2 Geliştirme Sunucusunu Windows VPS’te Açığa Çıkarma (Uzaktan Erişim)

Yerel bir makinede geliştirme sunucusuna yalnızca localhost üzerinden erişilebilir. Bir VPS’te ise genellikle internet üzerinden yerel tarayıcınızdan erişmek istersiniz. Bunun için iki değişiklik gereklidir:

Sunucuyu tüm ağ arayüzlerine bağlayın:

Vite için vite.config.js (veya vite.config.ts) dosyasını düzenleyin:

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

export default defineConfig({
  plugins: [react()],
  server: {
    host: '0.0.0.0',
    port: 5173,
  },
})

CRA için başlatmadan önce HOST ortam değişkenini ayarlayın:

set HOST=0.0.0.0
npm start

Windows Güvenlik Duvarı’nda portu açın:

netsh advfirewall firewall add rule name="React Dev Server" dir=in action=allow protocol=TCP localport=5173

Bundan sonra geliştirme sunucusuna herhangi bir tarayıcıdan http://<your-vps-ip>:5173 adresinden erişebilirsiniz.

Güvenlik uyarısı: Gerçek veri işleyen herhangi bir ortamda, kimlik doğrulaması olmadan bir geliştirme sunucusunu üretim VPS’inde kamuya açık internete asla maruz bırakmayın. Gerçek veri işleyen her ortam için bir ters proxy (Nginx veya URL Rewrite ile IIS) veya VPN tüneli kullanın.

Adım 4: Proje Yapısı ve Temel Dosyalar

İskelet yapısını anlamak, dosyaları değiştirmeye başladığınızda karışıklığı önler:

my-react-app/
├── public/             # Static assets served as-is (favicon, robots.txt)
├── src/
│   ├── assets/         # Images, fonts imported by components
│   ├── App.jsx         # Root component
│   ├── App.css         # Root component styles
│   ├── main.jsx        # Entry point — mounts <App /> into index.html
│   └── index.css       # Global styles
├── index.html          # HTML shell — Vite injects the bundle here
├── vite.config.js      # Vite configuration
├── package.json        # Dependencies and scripts
└── node_modules/       # Installed packages (never commit this)

src/main.jsx dosyası, uygulamanın giriş noktasıdır. Kök bileşeni index.html içindeki #root div’ine bağlamak için ReactDOM.createRoot()‘ı çağırır. Oluşturduğunuz her bileşen nihayetinde bu ağaca aktarılacaktır.

Adım 5: Üretim için Derleme

Uygulama dağıtıma hazır olduğunda, optimize edilmiş statik bir derleme oluşturun:

npm run build

Bu komut Vite’ın Rollup tabanlı paketleyicisini (veya CRA için Webpack’i) çağırır; bu paketleyici:

• JSX ve modern JavaScript’i tarayıcıyla uyumlu ES5/ES2015+’a dönüştürür
• Paketten kullanılmayan kodu tree-shake ile temizler
• JavaScript, CSS ve HTML’yi küçültür
• Uzun vadeli tarayıcı önbelleği için içerik karma değerli dosya adları oluşturur
• Her şeyi dist/ dizinine (Vite) veya build/ dizinine (CRA) çıktı olarak verir

Dağıtmadan önce üretim derlemesini yerel olarak önizlemek için:

npm run preview

dist/ içeriği tamamen statik dosyalardan (HTML, JS, CSS, varlıklar) oluşur. Bunlar herhangi bir web sunucusu tarafından sunulabilir — Windows Server’da IIS, Nginx, Apache veya statik bir barındırma hizmeti.

Derlemeyi Windows Server’daki IIS’e Dağıtma

VPS’iniz IIS çalıştırıyorsa, dist/ klasörünü işaret eden yeni bir site yapılandırın. React SPA’ları istemci tarafı yönlendirme kullandığından, tüm 404’leri index.html‘e yönlendirmek için bir URL Rewrite kuralı eklemeniz gerekir:

<configuration>
  <system.webServer>
    <rewrite>
      <rules>
        <rule name="React SPA" stopProcessing="true">
          <match url=".*" />
          <conditions logicalGrouping="MatchAll">
            <add input="{REQUEST_FILENAME}" matchType="IsFile" negate="true" />
            <add input="{REQUEST_FILENAME}" matchType="IsDirectory" negate="true" />
          </conditions>
          <action type="Rewrite" url="/index.html" />
        </rule>
      </rules>
    </rewrite>
  </system.webServer>
</configuration>

Bu kural olmadan, /dashboard gibi bir rotaya doğrudan yapılan her gezinti, React uygulamasını yüklemek yerine IIS’den 404 döndürür.

React ön yüzünü bir arka uç API’siyle birlikte sunuyorsanız ve yönetilen bir kontrol paneli ortamına ihtiyaç duyuyorsanız, cPanel ile VPS sanal ana bilgisayar yapılandırmasını ve SSL sonlandırmasını basitleştirebilir.

Adım 6: Uygulamayı HTTPS ile Güvenli Hale Getirme

Üretim ortamındaki bir React uygulaması HTTPS üzerinden sunulmalıdır. Tarayıcılar karışık içerik isteklerini engeller ve birçok tarayıcı API’si (service worker’lar, coğrafi konum, pano) güvenli bağlamlara kısıtlıdır.

VPS üzerinde barındırılan bir dağıtım için:

1. Alanınız için bir SSL sertifikası edinin. AlexHost, doğrudan VPS’inize kurulabilen SSL Sertifikaları sunmaktadır.
2. IIS’i veya ters proxy’nizi 443 numaralı portta TLS sonlandıracak ve HTTP’yi (port 80) HTTPS’ye yönlendirecek şekilde yapılandırın.
3. Yerel HTTPS testi için CRA’nın yerleşik sunucusunu kullanıyorsanız HTTPS ortam değişkenini true olarak ayarlayın.

VPS’inize yönlendirilmiş bir alan adınız henüz yoksa, önce Alan Adı Kaydı üzerinden bir alan adı kaydedin ve DNS A kaydını VPS IP adresinize işaret edecek şekilde yapılandırın.

Adım 7: Yaygın Sorunları Giderme

node veya npm Tanınmıyor

Bu, Node.js kurulum dizininin sistem PATH‘inde olmadığı anlamına gelir. Manuel olarak düzeltin:

1. Win + R tuşlarına basın, sysdm.cpl yazın, Enter’a basın.
2. Gelişmiş > Ortam Değişkenleri‘ne gidin.
3. Sistem Değişkenleri altında Path‘ı bulun ve Düzenle‘ye tıklayın.
4. C:Program Filesnodejs‘ı yeni bir giriş olarak ekleyin.
5. Tüm iletişim kutularında Tamam’a tıklayın, ardından yeni bir terminal penceresi açın.

npm Kurulumu Sırasında EACCES veya İzin Reddedildi Hataları

Windows Server’da bu durum genellikle npm’nin kısıtlı bir kullanıcı olarak çalıştırılmasından kaynaklanır. PowerShell’i Yönetici olarak çalıştırın ya da npm’nin önbellek ve global dizinlerini mevcut kullanıcının sahip olduğu bir yola yapılandırın:

npm config set cache "C:npm-cache"
npm config set prefix "C:npm-global"

Port Zaten Kullanımda

5173 veya 3000 portu başka bir işlem tarafından kullanılıyorsa:

netstat -ano | findstr :5173

Son sütundaki PID’yi belirleyin, ardından:

taskkill /PID <PID> /F

Alternatif olarak, vite.config.js dosyasındaki portu değiştirin veya --port‘ı bayrak olarak geçin:

npm run dev -- --port 3001

npm ERR! code EINTEGRITY (Sağlama Toplamı Uyuşmazlığı)

Bu, bozuk bir npm önbelleğine işaret eder. Önbelleği temizleyin ve yeniden deneyin:

npm cache clean --force
npm install

İlk Çalıştırmada Yavaş npm install

Bir React projesinin ilk bağımlılık kurulumu, VPS ağ verimine ve disk I/O’suna bağlı olarak 2–5 dakika sürebilir. Sürekli zaman aşımına uğruyorsa, VPS’in 443 numaralı portta registry.npmjs.org‘e giden erişiminin olup olmadığını kontrol edin. Bazı veri merkezi güvenlik duvarı politikaları bunu varsayılan olarak engeller.

Karar Matrisi: VPS’iniz için Doğru React Kurulumunu Seçme

Pratik Temel Kontrol Listesi

• Otomatik PATH kaydını sağlamak için .zip arşivi değil, .msi yükleyicisini kullanarak Node.js’in LTS sürümünü yükleyin.
• Tüm yeni React projeleri için npx create vite@latest kullanın — CRA kullanımdan kaldırılmıştır ve sıfırdan geliştirme için kullanılmamalıdır.
• Bir VPS’te, geliştirme sunucusuna uzaktan erişmek için vite.config.js dosyasında host: '0.0.0.0' ayarlayın ve ilgili güvenlik duvarı portunu açın.
• Doğrudan URL erişiminde istemci tarafı yönlendirmenin bozulmaması için tüm dosya ve dizin olmayan istekleri index.html‘e yönlendiren bir IIS URL Rewrite kuralı ekleyin.
• Üretim derlemelerini her zaman HTTPS üzerinden sunun; yayına geçmeden önce bir SSL sertifikası edinin ve yükleyin.
• Dağıtmadan önce npm run build çalıştırın ve dist/ çıktısını inceleyin — paket boyutlarını npm run build -- --report veya vite-bundle-visualizer kullanarak kontrol edin.
• node_modules/‘ı sürüm kontrolüne asla dahil etmeyin; her zaman .gitignore‘a ekleyin.
• Projeler arasında birden fazla Node sürümü gerekiyorsa, Node.js’i global olarak yeniden yüklemeden yönetmek için nvm-windows yükleyin.

SSS

React.js’in bir sunucuya “kurulması” mı gerekir, yoksa yalnızca derleme çıktısı mı yeterlidir?

React’in kendisi bir derleme zamanı bağımlılığıdır. npm run build‘ın üretim çıktısı düz HTML, CSS ve JavaScript’tir — sunucuda bunu sunmak için Node.js çalışma zamanı gerekmez. Node.js yalnızca derleme işlemini çalıştırdığınız makinede gereklidir.

npm run dev ile npm run build arasındaki fark nedir?

npm run dev, hot module replacement (HMR) ve küçültülmemiş kaynak haritalarıyla bir geliştirme sunucusu başlatır — performans için optimize edilmemiştir ve üretim trafiğini sunmak için asla kullanılmamalıdır. npm run build ise dağıtım için tasarlanmış, küçültülmüş, tree-shake edilmiş ve içerik karma değerli statik bir paket üretir.

Create React App neden kullanımdan kaldırıldı ve bunun yerine ne kullanmalıyım?

CRA, Vite’ın ESM-native geliştirme sunucusuna kıyasla önemli ölçüde daha yavaş derleme ve HMR sürelerine sahip olan Webpack 4’e dayanmaktadır. React ekibi, CRA’yı 2023’te belgelerinden resmi olarak kaldırmış ve artık SPA’lar için Vite’ı, full-stack uygulamalar için Next.js’i ve veri yoğun uygulamalar için Remix’i önermektedir.

Aynı Windows VPS’te aynı anda birden fazla React projesi çalıştırabilir miyim?

Evet. Her proje geliştirme sunucusunu farklı bir portta çalıştırır. Her projenin vite.config.js dosyasını benzersiz bir port değeriyle yapılandırın, her portu Windows Güvenlik Duvarı’nda açın ve isteğe bağlı olarak alt alan adlarını veya yolları ilgili porta yönlendirmek için IIS’i ters proxy olarak ayarlayın.

RDP oturumumu kapattıktan sonra React geliştirme sunucusunun çalışmaya devam etmesini nasıl sağlarım?

Bir işlem yöneticisi kullanın. PM2‘yi global olarak yükleyin (npm install -g pm2) ve geliştirme sunucusunu yönetilen bir işlem olarak başlatın: pm2 start npm --name "react-dev" -- run dev. PM2, işlemi terminal oturumundan bağımsız olarak canlı tutar ve sistem yeniden başlatmalarında otomatik olarak yeniden başlayacak şekilde yapılandırılabilir.