Inertia.js v3 Beta: Fitur Baru dan Panduan Migrasi

Inertia.js punya posisi unik di dunia full-stack Laravel: ia memungkinkan kamu membangun aplikasi Vue atau React tanpa membangun API terpisah. Tidak ada REST, tidak ada GraphQL — halaman di-render oleh Vue/React di sisi client, tapi data mengalir langsung dari controller Laravel seperti biasa. Inilah yang biasa disebut sebagai “the modern monolith.”

Versi 3 sekarang memasuki fase beta, dan pembaruannya bukan sekadar incremental. Beberapa keputusan arsitektural yang cukup besar dibuat: Axios dihapus sepenuhnya, konfigurasi SSR disederhanakan lewat Vite plugin baru, dan beberapa pola yang sebelumnya memerlukan boilerplate ekstra kini menjadi first-class feature. Jika kamu sudah bekerja dengan Inertia di proyek Laravel, artikel ini membahas apa yang berubah dan bagaimana cara migrasinya.

Mengapa v3 Layak Diperhatikan

Inertia v2 membawa banyak perbaikan, tapi beberapa friction poin tetap ada. SSR masih memerlukan proses Node terpisah saat development. Axios ikut terbundle meskipun tidak selalu dibutuhkan secara langsung. Pola seperti optimistic updates atau standalone HTTP requests harus diimplementasi sendiri tanpa dukungan resmi.

Versi 3 merespons semua itu dengan pendekatan yang lebih opinionated: kurangi konfigurasi yang diperlukan, sediakan primitive yang tepat untuk pola umum, dan perkecil bundle size. Persyaratan minimum pun naik — PHP 8.2+, Laravel 11+, dan jika menggunakan React maka React 19+ diperlukan.

Vite Plugin Baru yang Menghilangkan Boilerplate

Perubahan paling terasa di awal adalah hadirnya @inertiajs/vite. Plugin ini mengambil alih dua hal yang sebelumnya harus dikonfigurasi manual: resolusi halaman dan setup SSR.

Konfigurasi lama di vite.config.js memerlukan callback resolve yang mendeklarasikan cara menemukan komponen halaman. Di v3, semua itu dihandle oleh plugin:

// vite.config.js
import inertia from '@inertiajs/vite'
import laravel from 'laravel-vite-plugin'
import { defineConfig } from 'vite'

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

Entrypoint app.js juga menjadi lebih ringkas karena createInertiaApp tidak lagi memerlukan callback resolve:

// resources/js/app.js
import { createInertiaApp } from '@inertiajs/vue3'

createInertiaApp()

Satu hal yang signifikan: SSR di development tidak lagi membutuhkan proses Node terpisah. Cukup jalankan npm run dev dan Inertia otomatis melakukan server-side rendering. Untuk production, alurnya tetap sama — build dua kali lalu jalankan php artisan inertia:start-ssr.

Axios Dihapus, Digantikan XHR Client Bawaan

Inertia v3 tidak lagi menggunakan atau mem-bundle Axios. Semua request HTTP internal kini ditangani oleh XHR client bawaan yang lebih ringan. Ini langsung berdampak pada ukuran bundle — tidak ada lagi dependensi eksternal untuk operasi dasar.

Jika proyekmu saat ini menggunakan Axios interceptor untuk hal seperti menambahkan header custom atau menangani token, kamu perlu memigrasikannya ke interceptor baru milik Inertia atau memasang Axios adapter secara terpisah. Paket qs yang sebelumnya ikut terbundle juga sudah dilepas — jika aplikasimu mengimpornya langsung, pasang sendiri:

npm install qs

Standalone HTTP Request dengan useHttp

Sebelumnya, jika ingin melakukan request HTTP tanpa memicu navigasi halaman — misalnya untuk autocomplete atau real-time search — kamu harus menggunakan Axios atau fetch secara langsung di luar ekosistem Inertia. Versi 3 memperkenalkan useHttp sebagai solusi resmi.

Hook ini menyediakan reactive state, progress tracking untuk upload, dan request cancellation secara built-in:

<script setup>
import { useHttp } from '@inertiajs/vue3'

const http = useHttp({
    keyword: '',
    results: [],
})

function cariArtikel() {
    http.get('/api/artikel/search', {
        data: { q: http.keyword },
        onSuccess: (response) => {
            http.results = response.data
        },
    })
}
</script>

<template>
    <input v-model="http.keyword" @input="cariArtikel" placeholder="Cari artikel..." />
    <div v-if="http.processing">Mencari...</div>
    <ul>
        <li v-for="artikel in http.results" :key="artikel.id">{{ artikel.title }}</li>
    </ul>
</template>

State http.processing otomatis bernilai true saat request berlangsung dan kembali ke false setelah selesai — tidak perlu mengelola state loading secara manual.

Optimistic Updates

Ini salah satu tambahan yang paling berguna untuk interaksi seperti like, bookmark, atau perubahan status yang harus terasa instan. Dengan optimistic updates, UI diperbarui langsung sebelum respons server tiba, lalu di-sync dengan data asli ketika respons tersedia. Jika request gagal, props dikembalikan ke nilai semula secara otomatis.

router.optimistic((props) => ({
    artikel: {
        ...props.artikel,
        bookmarked: !props.artikel.bookmarked,
        bookmark_count: props.artikel.bookmark_count + 1,
    },
})).post(`/artikel/${artikelId}/bookmark`)

Fitur ini bekerja dengan router visit biasa, komponen <Form>, hook useForm, dan useHttp — jadi ada pilihan yang fleksibel tergantung konteks penggunaannya.

Instant Visits

Instant visits adalah fitur performa yang menarik: ketika user klik link, Inertia langsung menukar komponen halaman ke target tanpa menunggu respons server selesai. Permintaan server tetap berjalan di background, tapi transisi terasa instan.

<Link href="/dasbor" component="Dasbor">Dasbor</Link>

Shared props seperti data user atau notifikasi muncul segera karena sudah tersedia di client. Data spesifik halaman baru tiba saat request server selesai. Pola ini cocok untuk halaman yang strukturnya sudah dikenal client dan tidak bergantung sepenuhnya pada data baru dari server.

Layout Props

Sebelumnya, berbagi state antara layout dan halaman biasanya dilakukan lewat provide/inject di Vue atau Context di React. Inertia v3 memperkenalkan useLayoutProps sebagai cara yang lebih terstruktur.

Layout mendeklrasikan nilai default-nya:

<!-- resources/js/Layouts/AppLayout.vue -->
<script setup>
import { useLayoutProps } from '@inertiajs/vue3'

const { pageTitle, showBreadcrumb } = useLayoutProps({
    pageTitle: 'Aplikasi',
    showBreadcrumb: false,
})
</script>

<template>
    <header>
        <h1>{{ pageTitle }}</h1>
    </header>
    <slot />
</template>

Halaman kemudian bisa meng-override nilai tersebut lewat setLayoutProps():

<!-- resources/js/Pages/Artikel/Index.vue -->
<script setup>
import { setLayoutProps } from '@inertiajs/vue3'

setLayoutProps({
    pageTitle: 'Daftar Artikel',
    showBreadcrumb: true,
})
</script>

Ini jauh lebih bersih dibandingkan event bus atau melempar props secara manual antar komponen.

Exception Handling dari PHP

Sekarang ada cara resmi untuk menangani exception di sisi PHP dan menentukan halaman error yang tepat untuk ditampilkan, termasuk dengan shared data:

// app/Providers/AppServiceProvider.php
use Inertia\Inertia;
use Inertia\ExceptionResponse;

Inertia::handleExceptionsUsing(function (ExceptionResponse $response) {
    if (in_array($response->statusCode(), [403, 404, 500, 503])) {
        return $response->render('Error', [
            'status' => $response->statusCode(),
            'message' => $response->exception()->getMessage(),
        ])->withSharedData();
    }
});

Metode withSharedData() memastikan shared props seperti data user tetap tersedia di halaman error — sehingga layout aplikasi tetap berfungsi normal meski terjadi error.

Panduan Migrasi dari v2 ke v3

Upgrade ke v3 memerlukan beberapa langkah yang harus dilakukan secara berurutan.

Upgrade Dependensi

npm install @inertiajs/vue3@^3.0.0-beta @inertiajs/vite@^3.0.0-beta
composer require inertiajs/inertia-laravel:^3.0.0-beta

Republish Config dan Bersihkan Cache

Struktur file config berubah di v3. Jalankan ini untuk memperbarui file config:

php artisan vendor:publish --provider="Inertia\ServiceProvider" --force
php artisan view:clear

Ganti Method yang Dihapus

Beberapa API lama sudah dihapus. Dua yang paling umum ditemui:

// Sebelum (v2)
'komentar' => Inertia::lazy(fn () => Komentar::latest()->get()),

// Sesudah (v3)
'komentar' => Inertia::optional(fn () => Komentar::latest()->get()),

Update Event Listener

Dua event global berganti nama:

// Sebelum (v2)
router.on('invalid', (event) => { /* ... */ })
router.on('exception', (event) => { /* ... */ })

// Sesudah (v3)
router.on('httpException', (event) => { /* ... */ })
router.on('networkError', (event) => { /* ... */ })

Ganti router.cancel()

// Sebelum (v2)
router.cancel()

// Sesudah (v3)
router.cancelAll()
// atau batalkan hanya tipe tertentu
router.cancelAll({ async: false, prefetch: false })

Hal yang Perlu Diperhatikan Sebelum Upgrade

Ada beberapa perubahan kecil yang bisa luput dari perhatian saat migrasi:

• ESM only — Inertia v3 tidak lagi menyediakan build CommonJS. Jika ada konfigurasi require() untuk Inertia, ini perlu diubah ke import.
• future options dihapus — Semua flag eksperimental yang ada di v2 kini selalu aktif dan tidak perlu dikonfigurasi ulang.
• React <Deferred> berubah — Komponen ini tidak lagi mereset ke fallback saat partial reload. Gunakan slot prop reloading yang baru untuk menampilkan indikator loading.
• useForm processing — State processing dan progress sekarang hanya di-reset di callback onFinish, bukan langsung setelah respons diterima.

Jika kamu sudah membaca artikel hal-hal yang harus diperhatikan saat menggunakan Laravel + Inertia, beberapa pola yang dibahas di sana tetap relevan di v3 — hanya API-nya yang perlu disesuaikan.

Kesimpulan

Inertia.js v3 bukan sekadar pembaruan versi — ini adalah penyempurnaan filosofi “modern monolith” yang lebih konsisten. Dengan menghilangkan Axios, menyederhanakan SSR, dan menghadirkan primitive baru seperti useHttp dan optimistic updates, v3 mengurangi kebutuhan untuk keluar dari ekosistem Inertia hanya untuk menangani pola umum. Langkah selanjutnya: coba demo resmi di github.com/inertiajs/demo-v3 untuk melihat semua fitur baru bekerja bersama dalam satu aplikasi nyata.

Referensi

1. 1Inertia.js v3 Upgrade Guide — Dokumentasi Resmi
2. 2The Inertia v3 Beta is Here — Laravel News
3. 3Inertia.js Releases — GitHub