Client-Side Routing ve Nginx SPA Yapılandırması (404 Çözümü)

1. Özet ve Ne Öğreneceksiniz

React Router ve Vue Router gibi istemci taraflı (client-side) yönlendirme kütüphaneleri, sunucuya yeni bir HTTP isteği atmadan tarayıcı adres çubuğundaki URL'yi günceller. Ancak kullanıcı /dashboard gibi bir alt sayfadayken sayfayı yenilediğinde (F5) veya bağlantıyı doğrudan tarayıcıya yapıştırdığında, web sunucusu diskte /dashboard/index.html aradığı için 404 Not Found hatası döner. Bu rehberde Flyway yayın katmanının bu sorunu otomatik Nginx fallback kuralı ile nasıl çözdüğünü ve router yapılandırma standartlarını inceleyeceksiniz.

2. Bu Rehber Kimler İçin?

• ✅ React Router (v5/v6) veya Vue Router (v3/v4) kullanan Single Page Application (SPA) geliştiricileri.
• ✅ Canlı ortamda alt sayfalara doğrudan erişildiğinde 404 hatası alan ekipler.
• ✅ Nginx konfigürasyonu ile uğraşmadan istemci taraflı yönlendirmelerin güvenli çalışmasını isteyenler.

3. SPA Routing ve Nginx Mimarisi Nasıl Çalışır?

Geleneksel çok sayfalı (MPA) web sitelerinde her URL sunucuda fiziksel bir HTML dosyasına karşılık gelir. Single Page Application (SPA) mimarisinde ise tüm uygulama tek bir index.html ve buna bağlı JavaScript paketlerinden ibarettir.

• ✅ HTML5 History API: Tarayıcı içindeki JavaScript kodu (React Router / Vue Router), window.history.pushState() kullanarak sunucuya istek atmadan URL'yi değiştirir ve ilgili bileşeni ekrana çizer.
• ✅ Yenileme (Refresh) Çakışması: Kullanıcı F5 yaptığında tarayıcı istemci router'ını pas geçer ve doğrudan web sunucusundan /settings dosyasını ister. Sunucuda böyle bir dosya bulunmadığı için 404 hatası üretilir.
• ✅ Fallback Çözümü: Sunucu seviyesinde istenen dosya fiziksel olarak yoksa, yanıt olarak index.html dosyası döndürülür ve yönlendirme kontrolü JavaScript router'ına devredilir.

4. Flyway Otomatik SPA Fallback Yapılandırması

Flyway statik ve SPA projelerini yayınlarken Nginx sanal sunucu konfigürasyonuna otomatik olarak şu rewrite kuralını enjekte eder:

location / {
    try_files $uri $uri/ /index.html;
}

5. Kod Örnekleri (React Router & Vue Router)

İstemci tarafında router kurulumlarının doğru çalışması için örnek yapılandırmalar:

import { BrowserRouter, Routes, Route } from 'react-router-dom';
import Home from './Home';
import Dashboard from './Dashboard';

export default function App() {
  return (
    <BrowserRouter>
      <Routes>
        <Route path="/" element={<Home />} />
        <Route path="/dashboard" element={<Dashboard />} />
      </Routes>
    </BrowserRouter>
  );
}

import { createRouter, createWebHistory } from 'vue-router';
import Home from './Home.vue';
import Dashboard from './Dashboard.vue';

const routes = [
  { path: '/', component: Home },
  { path: '/dashboard', component: Dashboard }
];

export const router = createRouter({
  history: createWebHistory(),
  routes
});

6. Sorun Giderme Rehberi

7. Sıkça Sorulan Sorular

8. İlgili Dokümanlar

9. Sonraki Adımlar

SPA yönlendirme yapınızı doğruladıktan sonra özel alan adınızı bağlayabilir veya ortam değişkenlerinizi yapılandırarak yayın sürecinizi tamamlayabilirsiniz.