Inertia js, Laravel uygulamanızın üstüne ayrı bir REST veya GraphQL API yazmadan Vue ya da React ile modern bir tek sayfa uygulaması (SPA) kurmanızı sağlayan bir bağlayıcı katmandır. Klasik yaklaşımda backend ayrı bir API olur, frontend onu fetch ile tüketir, kimlik doğrulama için token yönetirsiniz ve aynı doğrulama mantığını iki kere yazarsınız. Inertia bu ikiliği ortadan kaldırır: controller'larınız HTML yerine bir bileşen adı ve veri (props) döndürür, tarayıcı ise sayfayı yeniden yüklemeden bu bileşeni render eder.
Inertia.js tam olarak nedir?
Inertia bir framework değildir; "framework olmayan bir framework" diye anılır. Sunucu tarafında Laravel route ve controller'larınızı aynen kullanmaya devam edersiniz. Fark şudur: bir sayfa döndürürken Blade view yerine Inertia::render('Users/Index', [...]) çağırırsınız. İlk istekte sunucu tam bir HTML belgesi yollar; sonraki tüm gezinmelerde Inertia, arka planda XHR ile yalnızca JSON döndürür ve istemci tarafı router bileşeni değiştirir. Böylece kullanıcı bir SPA deneyimi yaşar, siz ise sunucu yönlendirmeli bir uygulama yazmaya devam edersiniz.
Üç temel parça vardır:
- Sunucu adaptörü — Laravel için resmi
inertiajs/inertia-laravelpaketi. - İstemci adaptörü — Vue 3, React veya Svelte için
@inertiajs/vue3/@inertiajs/react. - Bir derleme aracı — Laravel'in varsayılanı olan Vite.
Yeni bir Laravel projesinde kurulum
En hızlı yol Laravel'in resmi başlangıç kitlerini (starter kit) kullanmaktır; bunlar Inertia + Vue veya React'i hazır kurulu getirir. Ancak mevcut bir projeye elle eklemek de basittir. Önce sunucu paketini kurun:
composer require inertiajs/inertia-laravel
php artisan inertia:middlewareinertia:middleware komutu HandleInertiaRequests middleware'ini oluşturur; bunu bootstrap/app.php içindeki web middleware grubuna ekleyin. Ardından kök Blade şablonunu hazırlayın — uygulamanın tek HTML iskeleti budur. resources/views/app.blade.php:
<!DOCTYPE html>
<html>
<head>
@vite(['resources/js/app.js'])
@inertiaHead
</head>
<body>
@inertia
</body>
</html>İstemci tarafını bağlamak
Şimdi Vue örneğiyle ilerleyelim. NPM paketlerini kurun ve giriş dosyasını oluşturun:
npm install @inertiajs/vue3 vue
npm install --save-dev @vitejs/plugin-vueresources/js/app.js dosyasında Inertia uygulamasını başlatın:
import { createApp, h } from 'vue'
import { createInertiaApp } from '@inertiajs/vue3'
createInertiaApp({
resolve: name =>
import(`./Pages/${name}.vue`),
setup({ el, App, props, plugin }) {
createApp({ render: () => h(App, props) })
.use(plugin)
.mount(el)
},
})React kullanıyorsanız mantık aynıdır; yalnızca @inertiajs/react paketini ve createRoot ile mount eden bir setup kullanırsınız. resolve fonksiyonu, controller'dan gelen bileşen adını (örneğin Users/Index) Pages klasöründeki gerçek dosyaya eşler.
Controller'dan sayfa döndürmek
İşin güzel tarafı burada: artık JSON kaynağı, serializer veya ayrı API route'u yok. Bir controller doğrudan bir bileşen ve onun prop'larını döndürür.
use Inertia\Inertia;
class UserController extends Controller
{
public function index()
{
return Inertia::render('Users/Index', [
'users' => User::query()
->select('id', 'name', 'email')
->get(),
]);
}
}Karşılığında resources/js/Pages/Users/Index.vue bileşeni bu prop'u alır:
<script setup>
import { Link } from '@inertiajs/vue3'
defineProps({ users: Array })
</script>
<template>
<ul>
<li v-for="user in users" :key="user.id">
<Link :href="`/users/${user.id}`">{{ user.name }}</Link>
</li>
</ul>
</template>Buradaki <Link> bileşeni sıradan bir <a> üretir ama tıklamayı yakalayıp tam sayfa yenilemesi yerine Inertia ziyareti yapar. Form göndermek için ise useForm yardımcısı vardır; doğrulama hatalarını otomatik olarak Laravel'in session error bag'inden alıp form.errors içinde sunar.
Paylaşılan veri, SSR ve diğer güçlü yönler
HandleInertiaRequests middleware'indeki share() metodu, her sayfaya otomatik geçen global prop'lar tanımlamanızı sağlar — oturum açmış kullanıcı, flash mesajları veya yetki bilgileri için idealdir. SEO veya ilk yükleme performansı kritikse Inertia'nın sunucu tarafı render (SSR) desteğini açabilirsiniz; php artisan inertia:start-ssr ile bir Node süreci sayfayı sunucuda önceden render eder. Tembel yüklenen prop'lar (Inertia::lazy()) ve kısmi yeniden yüklemeler (only seçeneği) ile yalnızca gereken veriyi taşıyarak ağ trafiğini düşürürsünüz.
Inertia'nın temel takası şudur: gerçek anlamda ayrık bir API'niz olmaz. Aynı backend'i bir mobil uygulamaya veya üçüncü taraf entegrasyonlara açacaksanız yine de bir API katmanı yazmanız gerekir. Ama tek tüketicisi kendi web arayüzünüz olan uygulamalarda Inertia, ciddi miktarda yinelenen kodu ortadan kaldırır.
Sık Sorulan Sorular
Inertia.js ayrı bir API'nin yerini tutar mı?
Web arayüzünüz için evet — controller'lar doğrudan bileşen render ettiği için ayrı bir REST/GraphQL katmanına gerek kalmaz. Ancak aynı veriyi mobil uygulama gibi başka istemcilere sunmanız gerekiyorsa yine de geleneksel bir API yazmalısınız.
Vue mi yoksa React mı seçmeliyim?
İkisi de resmi olarak desteklenir ve Inertia'nın sunucu tarafı tamamen aynıdır. Seçim ekibinizin tecrübesine bağlıdır; mantık ve API neredeyse birebir aynı kalır, yalnızca bileşen sözdizimi değişir.
SEO için uygun mu?
Varsayılan istemci tarafı render arama motorları için yeterli olabilir, ancak garanti istiyorsanız Inertia'nın SSR modunu açın; böylece sayfanın ilk HTML'i sunucuda üretilir ve botlar tam içeriği görür.
Modern bir SPA mı kurmak istiyorsunuz, mevcut bir Laravel projesini mi Inertia'ya taşımak istiyorsunuz? Backend mimarisinden Vue/React arayüzüne kadar uçtan uca yardımcı olabilirim. Benimle iletişime geçin ve projenizi konuşalım.