Laravel Breeze adalah starter kit autentikasi yang ringan untuk Laravel. Saat dipadukan dengan Inertia.js, developer dapat membangun aplikasi dengan pengalaman single-page app tanpa harus memisahkan backend API dan frontend secara penuh. Dalam konteks aplikasi multi halaman, pendekatan ini sangat cocok karena struktur route tetap terasa seperti aplikasi server-rendered Laravel, tetapi halaman dirender oleh komponen frontend melalui Inertia.

Artikel ini membahas alur kerja praktis penggunaan Laravel Breeze berbasis Inertia.js, mulai dari instalasi, generate scaffold autentikasi, login, register, reset password, proteksi route, berbagi data user ke semua halaman melalui shared props, logout, redirect intended, penanganan error validasi, hingga pemisahan layout publik dan dashboard.

Memahami Peran Breeze dan Inertia.js

Laravel Breeze menyediakan fondasi autentikasi yang umum dibutuhkan aplikasi: login, register, lupa password, reset password, verifikasi email, dan logout. Breeze juga menghasilkan controller, route, middleware, view layer, serta integrasi frontend sesuai stack yang dipilih.

Inertia.js bertindak sebagai jembatan antara Laravel dan frontend framework seperti Vue atau React. Alih-alih mengembalikan blade template untuk setiap halaman, controller Laravel mengembalikan response Inertia yang memuat nama komponen dan props. Browser tetap berpindah halaman seperti aplikasi web biasa, tetapi render dilakukan oleh frontend framework.

Keuntungan pendekatan ini untuk aplikasi multi halaman:

  • Route dan middleware tetap dikelola di Laravel.
  • Autentikasi session-based tetap sederhana dan aman.
  • Tidak perlu membuat API terpisah hanya untuk form login dan register.
  • Validasi server dan redirect Laravel tetap bekerja alami.

Trade-off utamanya adalah frontend masih sangat bergantung pada backend Laravel. Jika Anda membutuhkan frontend dan backend yang benar-benar independen, pendekatan API + SPA murni mungkin lebih cocok.

Instalasi dan Generate Auth Scaffold

Menyiapkan proyek

Jika proyek Laravel belum dibuat, buat terlebih dahulu lalu siapkan database dan file environment.

composer create-project laravel/laravel nama-aplikasi
cd nama-aplikasi
cp .env.example .env
php artisan key:generate

Setelah itu, atur koneksi database di file .env.

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=app_db
DB_USERNAME=root
DB_PASSWORD=

Memasang Breeze dengan Inertia

Pasang package Breeze, lalu generate scaffold Inertia sesuai frontend stack yang digunakan. Contoh berikut menggunakan Vue, tetapi konsepnya sama untuk React.

composer require laravel/breeze --dev
php artisan breeze:install vue
npm install
npm run build
php artisan migrate

Perintah tersebut akan menghasilkan beberapa komponen penting:

  • Route autentikasi seperti login, register, forgot password, reset password.
  • Controller autentikasi bawaan Laravel.
  • Halaman Inertia untuk area auth dan dashboard.
  • Middleware serta konfigurasi session yang relevan.

Saat development, biasanya Anda akan menjalankan server Laravel dan bundler frontend secara bersamaan:

php artisan serve
npm run dev

Alur Login, Register, dan Reset Password

Route dan form login

Breeze sudah menyiapkan route login. Dalam pendekatan Inertia, form di frontend akan mengirim request POST ke route Laravel, lalu controller memproses autentikasi menggunakan session.

Contoh halaman login Inertia biasanya memanfaatkan helper form dari adapter Inertia:

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

const form = useForm({
  email: '',
  password: '',
  remember: false,
})

const submit = () => {
  form.post(route('login'))
}
</script>

Kenapa ini efektif? Karena useForm sudah menangani status loading, reset field, serta error validasi dari backend dalam format yang mudah dipakai di komponen.

Contoh menampilkan error validasi:

<div v-if="form.errors.email" class="text-red-600">
  {{ form.errors.email }}
</div>

Kesalahan umum di tahap ini adalah mencoba memvalidasi semuanya di frontend lalu mengabaikan validasi server. Pada Laravel + Inertia, validasi server tetap sumber kebenaran utama. Validasi frontend boleh ditambahkan untuk UX, tetapi jangan menggantikan validasi backend.

Register user

Flow register juga serupa. Form dikirim ke route register, lalu Laravel membuat user baru dan melakukan login otomatis jika konfigurasi default Breeze dipakai.

Pastikan model User memiliki atribut yang boleh diisi massal:

protected $fillable = [
    'name',
    'email',
    'password',
];

Jika field tambahan seperti phone atau role ingin disimpan saat registrasi, Anda perlu memperbarui migration, request validation, dan controller atau action terkait. Jangan lupa membatasi field yang benar-benar aman untuk diisi user, karena kesalahan di $fillable bisa membuka celah mass assignment.

Forgot password dan reset password

Breeze juga menyediakan alur lupa password dan reset password. Flow dasarnya:

  1. User membuka halaman forgot password.
  2. User mengirim email.
  3. Laravel mengirim tautan reset password via email.
  4. User membuka link token reset.
  5. User memasukkan password baru.

Untuk pengujian lokal, Anda bisa menggunakan mail driver seperti log atau mailpit.

MAIL_MAILER=log

Dengan konfigurasi ini, link reset password akan ditulis ke log sehingga mudah diuji tanpa SMTP sungguhan.

Jika email reset tidak terkirim, periksa konfigurasi mailer, queue, dan environment aplikasi. Pada banyak kasus, masalahnya bukan pada Breeze, tetapi pada transport email yang belum benar.

Proteksi Route dengan Middleware Auth

Salah satu kelebihan Laravel untuk aplikasi multi halaman adalah proteksi route sangat mudah dan eksplisit. Anda bisa memisahkan area publik dan area yang memerlukan login menggunakan middleware auth.

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

Route::get('/', function () {
    return Inertia::render('Welcome');
})->name('home');

Route::middleware('auth')->group(function () {
    Route::get('/dashboard', function () {
        return Inertia::render('Dashboard');
    })->name('dashboard');

    Route::get('/profile', function () {
        return Inertia::render('Profile/Index');
    })->name('profile.index');
});

Saat user yang belum login mencoba mengakses route di dalam grup auth, Laravel otomatis akan mengarahkannya ke halaman login. Di sinilah konsep redirect intended menjadi penting.

Redirect intended setelah login

Laravel menyimpan URL tujuan awal ketika user diarahkan ke login karena belum terautentikasi. Setelah login berhasil, user akan dikembalikan ke halaman yang semula ingin diakses, bukan selalu ke dashboard. Ini meningkatkan UX, terutama pada aplikasi yang memiliki banyak halaman privat.

Secara umum, mekanisme ini sudah ditangani oleh flow autentikasi Laravel. Jika Anda menyesuaikan controller atau response login, pastikan perilaku redirect intended tidak rusak. Kesalahan yang sering terjadi adalah memaksa redirect statis ke satu halaman dan mengabaikan tujuan awal user.

Berbagi Data User ke Semua Halaman dengan Shared Props

Pada aplikasi multi halaman, data user yang sedang login sering dibutuhkan di banyak tempat: navbar, sidebar, dropdown akun, atau pengecekan role sederhana di frontend. Daripada mengirim data user dari setiap controller secara manual, gunakan shared props.

Tempat yang umum untuk ini adalah middleware Inertia bawaan aplikasi, biasanya di HandleInertiaRequests.

public function share($request): array
{
    return array_merge(parent::share($request), [
        'auth' => [
            'user' => $request->user()
                ? [
                    'id' => $request->user()->id,
                    'name' => $request->user()->name,
                    'email' => $request->user()->email,
                ]
                : null,
        ],
        'flash' => [
            'success' => fn () => $request->session()->get('success'),
            'error' => fn () => $request->session()->get('error'),
        ],
    ]);
}

Dengan konfigurasi ini, setiap halaman Inertia dapat mengakses data user lewat props global. Contoh di Vue:

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

const page = usePage()
const user = page.props.auth.user
</script>

Penting untuk hanya membagikan field yang benar-benar diperlukan. Jangan mengirim semua atribut model user tanpa filter, terutama jika ada field sensitif atau metadata internal.

Logout dan Pengelolaan Session

Logout pada Breeze bekerja menggunakan request POST, bukan GET. Ini adalah praktik yang baik karena logout mengubah state session dan sebaiknya tidak dipicu lewat request idempoten seperti GET.

Contoh tombol logout pada komponen Inertia:

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

const logout = () => {
  router.post(route('logout'))
}
</script>

Di backend, Laravel akan menghapus autentikasi session, melakukan invalidasi session, dan biasanya merotasi token CSRF sesuai flow bawaan. Jika logout terasa tidak bekerja, periksa beberapa hal berikut:

  • Apakah route logout dipanggil dengan method POST.
  • Apakah middleware web aktif sehingga session tersedia.
  • Apakah ada cache browser atau state frontend lama yang belum tersinkronisasi.

Menangani Error Validasi dan Flash Message

Keunggulan kombinasi Laravel dan Inertia adalah error validasi dari backend langsung tersedia di halaman tanpa menulis parsing response secara manual seperti pada SPA berbasis API biasa. Saat validasi gagal, Laravel mengembalikan redirect beserta error bag, lalu Inertia menyediakannya di form object atau page props.

Untuk notifikasi keberhasilan, gunakan flash message dari session dan bagikan lewat shared props seperti contoh sebelumnya. Ini berguna setelah update profil, ubah password, atau operasi CRUD lain di area dashboard.

Tips debugging saat error validasi tidak muncul:

  • Pastikan form dikirim melalui helper Inertia, bukan fetch manual tanpa penanganan error.
  • Pastikan nama field di frontend sama dengan nama field validasi di backend.
  • Periksa tab network di browser untuk melihat status response dan payload.
  • Pastikan tidak ada exception lain yang terjadi sebelum validasi diproses.

Menyesuaikan Layout untuk Area Publik dan Dashboard

Aplikasi multi halaman biasanya membutuhkan pemisahan antarmuka antara halaman publik dan area dashboard. Dengan Inertia, pola yang umum adalah membuat dua layout terpisah: PublicLayout untuk halaman seperti home, login, register, dan DashboardLayout untuk halaman setelah login.

Contoh manfaat pemisahan layout:

  • Navbar publik dan sidebar dashboard tidak bercampur.
  • Komponen auth user hanya dimuat di area privat.
  • Struktur halaman lebih konsisten dan mudah dirawat.

Secara praktik, setiap page component dapat menetapkan layout yang sesuai. Misalnya halaman dashboard menggunakan layout dengan sidebar dan topbar, sedangkan halaman publik menggunakan layout sederhana dengan header umum.

Hal yang perlu diperhatikan adalah jangan menaruh logika otorisasi hanya di layout frontend. Layout hanya mengatur tampilan. Proteksi akses tetap harus dilakukan di route atau middleware backend. Menyembunyikan menu dashboard di frontend tidak cukup untuk mencegah akses langsung ke URL privat.

Praktik Baik dalam Pengembangan Sehari-hari

Gunakan middleware untuk keamanan, bukan sekadar kondisi di frontend

Jika sebuah halaman harus privat, proteksi dengan auth. Jika ada pembatasan tambahan seperti admin-only, gunakan policy, gate, atau middleware khusus.

Batasi shared props

Semakin banyak data global yang dibagikan ke semua halaman, semakin besar payload yang dikirim setiap request Inertia. Bagikan hanya data yang sering dipakai dan aman untuk diekspos.

Manfaatkan route name

Menggunakan nama route seperti route('dashboard') lebih aman dibanding hardcode URL, terutama saat struktur path berubah di masa depan.

Uji alur autentikasi end-to-end

Minimal uji skenario berikut:

  • User tamu mengakses dashboard lalu diarahkan ke login.
  • Setelah login, user kembali ke halaman intended.
  • Register membuat akun baru dan session aktif.
  • Reset password menghasilkan password baru yang valid.
  • Logout benar-benar menghapus session.

Penutup

Laravel Breeze + Inertia.js adalah kombinasi yang efisien untuk membangun autentikasi pada aplikasi multi halaman. Developer tetap mendapatkan kenyamanan route, middleware, session, dan validasi khas Laravel, sambil menikmati pengalaman rendering komponen frontend yang lebih modern.

Untuk implementasi praktis, fokus utama yang perlu dipahami adalah: generate scaffold dengan benar, gunakan route dan middleware auth untuk proteksi, manfaatkan shared props untuk data user global, pertahankan redirect intended agar UX tetap baik, dan pisahkan layout publik serta dashboard supaya struktur aplikasi rapi.

Jika fondasi ini sudah tertata, Anda bisa melanjutkan ke kebutuhan yang lebih lanjut seperti role-based access control, pengelolaan profil, verifikasi email, atau integrasi testing otomatis tanpa harus mengubah pendekatan dasar autentikasi yang sudah stabil.