Memulai Inertia.js dengan Laravel 11 dan Vue 3 dari Nol

Inertia.js adalah pendekatan untuk membangun aplikasi web modern tanpa harus memisahkan backend dan frontend menjadi dua proyek yang benar-benar terpisah. Dengan Inertia, Laravel tetap menangani routing dan controller di sisi server, sementara Vue 3 digunakan untuk merender halaman di sisi klien. Hasilnya adalah pengalaman seperti Single Page Application (SPA), tetapi dengan alur kerja yang tetap dekat dengan pola aplikasi Laravel tradisional.

Dalam panduan ini, kita akan menyiapkan proyek Laravel 11 + Inertia.js + Vue 3 dari nol. Fokusnya bukan hanya agar aplikasi berjalan, tetapi juga memahami mengapa setiap bagian dibutuhkan: mulai dari instalasi paket, konfigurasi Vite, middleware Inertia, root template, pembuatan halaman pertama, routing, hingga pengiriman data dari controller ke komponen Vue.

Panduan ini cocok jika Anda ingin membangun aplikasi CRUD, dashboard admin, atau panel internal dengan pengalaman frontend modern tanpa kompleksitas penuh dari arsitektur API terpisah.

Mengapa Memilih Inertia.js?

Sebelum masuk ke implementasi, penting memahami posisi Inertia di antara dua pendekatan umum berikut:

Blade tradisional: server merender HTML penuh di setiap request.
SPA murni dengan API terpisah: backend hanya mengembalikan JSON, frontend dikelola penuh oleh Vue/React.

Inertia berada di tengah. Laravel tetap mengurus route, middleware, autentikasi, validasi, dan controller seperti biasa. Namun, alih-alih merender Blade per halaman, controller mengembalikan page component Inertia beserta props yang akan dirender oleh Vue.

Perbandingan Alur Request

Blade: browser meminta URL, Laravel merender HTML lengkap, lalu browser memuat ulang halaman.

SPA + API: browser memuat shell frontend sekali, lalu frontend memanggil API terpisah untuk mendapatkan data JSON.

Inertia: browser meminta URL ke Laravel, Laravel mengembalikan respons Inertia yang berisi nama komponen halaman dan props. Vue mengganti halaman secara dinamis tanpa reload penuh.

Kelebihannya:

Tidak perlu membangun dan memelihara REST API terpisah untuk halaman internal.
Autentikasi, policy, middleware, dan validasi Laravel tetap digunakan langsung.
Pengalaman navigasi terasa seperti SPA.

Trade-off-nya:

Inertia bukan pengganti API publik. Jika aplikasi Anda perlu dikonsumsi banyak client lain, API tetap relevan.
Anda tetap perlu memahami frontend modern, termasuk state, komponen, dan build tool.
Jika tidak hati-hati, props yang terlalu besar bisa membuat payload respons menjadi berat.

Prasyarat dan Membuat Proyek Laravel 11

Pastikan lingkungan Anda sudah memiliki:

PHP 8.2 atau lebih baru
Composer
Node.js dan npm
Database jika dibutuhkan untuk pengembangan berikutnya

Buat proyek Laravel baru:

composer create-project laravel/laravel inertia-laravel-vue
cd inertia-laravel-vue

Setelah itu, jalankan server Laravel dan Vite nanti secara terpisah. Namun sebelum itu, kita instal dulu paket Inertia dan Vue.

Instalasi Inertia.js dan Vue 3

1. Instal Paket Server-side Inertia

Di sisi Laravel, Anda memerlukan adapter Inertia untuk PHP:

composer require inertiajs/inertia-laravel

Paket ini menyediakan integrasi Inertia dengan Laravel, termasuk helper seperti Inertia::render(), middleware, dan mekanisme berbagi data global.

2. Instal Paket Client-side untuk Vue 3

Di sisi frontend, instal Vue 3 dan adapter Inertia untuk Vue:

npm install vue @vitejs/plugin-vue @inertiajs/vue3

Jika proyek Anda belum memiliki plugin Vue di Vite, paket @vitejs/plugin-vue akan digunakan dalam konfigurasi berikutnya.

3. Pastikan Dependensi Frontend Terpasang

npm install

Perintah ini memastikan seluruh dependensi JavaScript diunduh dan siap dipakai oleh Vite.

Konfigurasi Vite untuk Vue 3

Laravel 11 sudah menggunakan Vite sebagai build tool frontend. Kita perlu memberi tahu Vite agar bisa memproses file Vue.

Edit file vite.config.js menjadi seperti ini:

import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';
import vue from '@vitejs/plugin-vue';

export default defineConfig({
    plugins: [
        laravel({
            input: ['resources/js/app.js'],
            refresh: true,
        }),
        vue(),
    ],
});

Mengapa perlu plugin Vue? Karena file .vue adalah Single File Component yang tidak bisa dipahami JavaScript biasa tanpa proses kompilasi. Plugin ini menangani parsing template, script, dan style di dalam file Vue.

Membuat Middleware Inertia

Inertia memerlukan middleware untuk menangani request khusus Inertia dan membagikan data global ke semua halaman jika diperlukan.

Buat middleware dengan perintah berikut:

php artisan inertia:middleware

Perintah tersebut akan membuat file middleware, biasanya di:

app/Http/Middleware/HandleInertiaRequests.php

Isi dasarnya akan terlihat seperti ini:

<?php

namespace App\Http\Middleware;

use Illuminate\Http\Request;
use Inertia\Middleware;

class HandleInertiaRequests extends Middleware
{
    protected $rootView = 'app';

    public function version(Request $request): ?string
    {
        return parent::version($request);
    }

    public function share(Request $request): array
    {
        return array_merge(parent::share($request), [
            // data global di sini
        ]);
    }
}

Perhatikan properti $rootView = 'app'. Artinya Inertia akan menggunakan file Blade bernama resources/views/app.blade.php sebagai template root untuk memuat aplikasi Vue.

Selanjutnya, pastikan middleware ini terdaftar di stack web. Pada Laravel 11, pengaturan middleware biasanya dilakukan melalui bootstrap aplikasi. Jika proyek Anda belum memasang middleware ini, tambahkan ke grup web sesuai struktur proyek Laravel 11 Anda.

Jika Anda menggunakan starter kit atau instalasi tertentu, middleware bisa saja sudah terhubung. Selalu cek apakah request Inertia diproses lewat middleware ini saat debugging.

Membuat Root Template Blade

Walaupun halaman utama dirender oleh Vue, Anda tetap membutuhkan satu file Blade sebagai root HTML. Buat file resources/views/app.blade.php:

<!DOCTYPE html>
<html lang="id">
<head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title inertia>Laravel Inertia Vue</title>
    @vite('resources/js/app.js')
    @inertiaHead
</head>
<body>
    @inertia
</body>
</html>

Ada dua directive penting di sini:

@inertia: tempat aplikasi Inertia dirender.
@inertiaHead: untuk mengelola elemen head seperti title dan meta dari komponen halaman.

Ini adalah salah satu perbedaan penting dibanding Blade biasa. Blade root ini hanya menjadi kerangka utama, sedangkan konten halaman diisi oleh komponen Vue berdasarkan respons dari Laravel.

Membuat Entry Point Vue dan Inertia

Sekarang buat file resources/js/app.js:

import { createApp, h } from 'vue';
import { createInertiaApp } from '@inertiajs/vue3';
import { resolvePageComponent } from 'laravel-vite-plugin/inertia-helpers';

createInertiaApp({
    resolve: (name) =>
        resolvePageComponent(
            `./Pages/${name}.vue`,
            import.meta.glob('./Pages/**/*.vue')
        ),
    setup({ el, App, props, plugin }) {
        createApp({ render: () => h(App, props) })
            .use(plugin)
            .mount(el);
    },
});

Kode ini melakukan beberapa hal penting:

Membuat aplikasi Inertia.
Mencari komponen halaman Vue di folder resources/js/Pages.
Memasang plugin Inertia ke aplikasi Vue.
Merender halaman yang diminta server ke elemen root di Blade.

Pendekatan import.meta.glob() membuat pemuatan halaman lebih rapi dan scalable karena setiap file di folder Pages bisa dipanggil berdasarkan nama dari controller.

Membuat Halaman Pertama

Buat folder dan file halaman pertama:

resources/js/Pages/Home.vue

Isi file-nya:

<script setup>
defineProps({
  title: String,
  message: String,
  users: Array,
})
</script>

<template>
  <div style="padding: 24px; font-family: Arial, sans-serif;">
    <h1>{{ title }}</h1>
    <p>{{ message }}</p>

    <h2>Daftar User</h2>
    <ul>
      <li v-for="user in users" :key="user.id">
        {{ user.name }} - {{ user.email }}
      </li>
    </ul>
  </div>
</template>

Komponen ini menerima props dari Laravel. Dengan script setup, deklarasi props menjadi ringkas dan mudah dibaca. Pada aplikasi nyata, Anda biasanya juga menambahkan layout, komponen reusable, dan utilitas lain.

Routing Web dan Controller Inertia

Sekarang buat route web yang mengembalikan halaman Inertia. Edit routes/web.php:

<?php

use Illuminate\Support\Facades\Route;
use Inertia\Inertia;

Route::get('/', function () {
    return Inertia::render('Home', [
        'title' => 'Halo dari Inertia.js',
        'message' => 'Halaman ini dirender oleh Vue 3, tetapi route tetap ditangani Laravel.',
        'users' => [
            ['id' => 1, 'name' => 'Andi', 'email' => 'andi@example.com'],
            ['id' => 2, 'name' => 'Budi', 'email' => 'budi@example.com'],
        ],
    ]);
});

Di sini, Inertia::render('Home', ...) berarti Laravel akan merender komponen resources/js/Pages/Home.vue dan mengirim props yang didefinisikan.

Untuk struktur yang lebih rapi, lebih baik gunakan controller:

php artisan make:controller HomeController

Lalu isi app/Http/Controllers/HomeController.php:

<?php

namespace App\Http\Controllers;

use Inertia\Inertia;
use Inertia\Response;

class HomeController extends Controller
{
    public function __invoke(): Response
    {
        return Inertia::render('Home', [
            'title' => 'Halo dari Inertia.js',
            'message' => 'Props ini dikirim dari controller Laravel ke komponen Vue.',
            'users' => [
                ['id' => 1, 'name' => 'Andi', 'email' => 'andi@example.com'],
                ['id' => 2, 'name' => 'Budi', 'email' => 'budi@example.com'],
            ],
        ]);
    }
}

Update route:

<?php

use App\Http\Controllers\HomeController;
use Illuminate\Support\Facades\Route;

Route::get('/', HomeController::class);

Menggunakan controller lebih mudah dipelihara saat logika mulai berkembang, misalnya mengambil data dari database, memeriksa otorisasi, atau memformat payload.

Struktur Folder yang Disarankan

Berikut struktur minimal yang rapi untuk proyek awal:

app/
├── Http/
│   ├── Controllers/
│   │   └── HomeController.php
│   └── Middleware/
│       └── HandleInertiaRequests.php
resources/
├── js/
│   ├── Pages/
│   │   └── Home.vue
│   └── app.js
└── views/
    └── app.blade.php
routes/
└── web.php
vite.config.js

Seiring aplikasi berkembang, Anda bisa menambahkan folder seperti Layouts, Components, dan Composables di dalam resources/js.

Menjalankan Proyek

Jalankan server Laravel:

php artisan serve

Di terminal lain, jalankan Vite:

npm run dev

Buka aplikasi di browser, biasanya di http://127.0.0.1:8000. Jika semua benar, Anda akan melihat halaman Vue dirender melalui Inertia.

Debugging dan Kesalahan Umum

1. Halaman putih atau komponen tidak muncul

Periksa apakah @vite('resources/js/app.js') ada di root template, dan pastikan npm run dev sedang berjalan.

2. Komponen page tidak ditemukan

Nama pada Inertia::render('Home') harus cocok dengan file resources/js/Pages/Home.vue. Huruf besar-kecil penting, terutama di lingkungan Linux.

3. Error terkait middleware

Jika request Inertia tidak diproses dengan benar, cek apakah HandleInertiaRequests benar-benar masuk ke grup middleware web.

4. Props tidak sesuai bentuk data

Jika di Vue Anda mengharapkan array tetapi controller mengirim object atau null, render bisa gagal atau menampilkan hasil tak terduga. Validasi bentuk data di controller dan deklarasikan props secara jelas di Vue.

5. Asset tidak termuat di production

Pastikan Anda menjalankan build produksi dengan:

npm run build

Lalu deploy file hasil build sesuai praktik deploy Laravel yang Anda gunakan.

Kapan Menggunakan Inertia dan Kapan Tidak?

Inertia sangat cocok jika:

Anda membangun aplikasi web internal atau dashboard.
Tim Anda nyaman dengan Laravel dan ingin menambahkan Vue tanpa memisahkan backend/frontend.
Anda ingin navigasi cepat ala SPA dengan logika backend tetap sederhana.

Inertia mungkin kurang cocok jika:

Anda perlu API publik yang akan dipakai mobile app atau pihak ketiga.
Frontend dan backend dikelola tim yang benar-benar terpisah.
Anda membutuhkan arsitektur frontend yang sepenuhnya independen dari server-side routing.

Penutup

Dengan Laravel 11, Inertia.js, dan Vue 3, Anda bisa membangun aplikasi modern tanpa harus membuat API terpisah hanya untuk kebutuhan halaman web. Alurnya tetap mengikuti cara kerja Laravel: route masuk ke controller, controller mengembalikan respons Inertia, lalu Vue merender page component menggunakan props yang dikirim server.

Dalam artikel ini, kita sudah menyiapkan fondasi penting: instalasi package server dan client, konfigurasi Vite, middleware Inertia, root template Blade, page pertama, routing web, dan pengiriman props dari controller ke Vue. Setelah tahap ini, langkah berikutnya yang biasanya dikerjakan adalah membuat layout bersama, menambahkan navigasi menggunakan komponen Link dari Inertia, menghubungkan data ke database, serta menangani form submit dan validasi.

Jika fondasi ini dipahami dengan benar, Anda akan lebih mudah mengembangkan aplikasi Inertia yang bersih, cepat, dan tetap nyaman dipelihara dalam ekosistem Laravel.

Quick Search

shopping_cart Keranjang