Kalau kamu pernah menulis fetch('/invoice/' + id) di komponen React, lalu route Laravel-nya berubah dan halaman itu diam-diam jadi 404, kamu sudah merasakan masalah yang coba diselesaikan Laravel Wayfinder. Paket resmi dari tim Laravel ini membaca daftar route dan controller di sisi server, lalu menghasilkan fungsi TypeScript bertipe lengkap untuk sisi klien. Tidak ada URL hardcode, tidak ada salah ketik nama parameter, dan kesalahan route ketahuan saat build — bukan saat user menekan tombol simpan.
Masalah Lama: Backend dan Frontend Punya Dua Sumber Kebenaran
Di aplikasi Laravel modern, route hidup di routes/web.php dan routes/api.php. Tapi frontend menyimpan salinan pengetahuannya sendiri: string URL di komponen, tipe parameter yang ditulis manual, dan daftar endpoint di file service. Selama aplikasi kecil, duplikasi ini tidak terasa. Begitu halaman lewat dua puluh, muncul gejala klasik: route di-rename, satu komponen terlewat, error baru ketahuan dari laporan user.
Ada juga masalah yang lebih halus: tipe. Route /orders/{order:number} menerima nomor pesanan, sedangkan /orders/{order} menerima primary key. Dari sisi TypeScript keduanya tampak sama-sama string | number, jadi tidak ada yang mengingatkan saat kamu mengirim id yang salah. Wayfinder menutup celah ini dengan membaca definisi route langsung dari router Laravel, termasuk binding model dan kolom yang dipakai.
Apa yang Sebenarnya Dihasilkan Wayfinder
Setelah dijalankan, Wayfinder menulis tiga direktori di dalam resources/js: actions, routes, dan wayfinder. Direktori actions berisi satu file per controller, routes berisi satu file per named route, sementara wayfinder menyimpan helper internal yang dipakai keduanya.
Satu hal yang penting dipahami: fungsi hasil generate tidak mengembalikan string. Fungsi itu mengembalikan objek berisi url dan method default. Pola inilah yang membuat Wayfinder bisa dipakai langsung oleh Inertia, karena Inertia perlu tahu metode HTTP selain URL-nya.
Instalasi: Composer, Vite Plugin, dan Generate Pertama
Syarat minimumnya PHP 8.2. Versi terbaru yang saya cek di Packagist adalah laravel/wayfinder v0.1.23, dengan dukungan illuminate/* 11, 12, dan 13 — artinya paket ini jalan di Laravel 11 sampai 13 tanpa penyesuaian.
composer require laravel/wayfinder
npm i -D @laravel/vite-plugin-wayfinder
php artisan wayfinder:generate
Plugin Vite dipakai supaya file TypeScript ikut diperbarui setiap kali route atau controller berubah saat npm run dev berjalan. Daftarkan di vite.config.ts:
import { wayfinder } from "@laravel/vite-plugin-wayfinder";
import { defineConfig } from "vite";
export default defineConfig({
plugins: [wayfinder()],
});
Kalau memakai Laravel Herd, ada opsi command untuk menunjuk binary PHP yang benar, misalnya herd php artisan wayfinder:generate. Opsi lain: path, routes, actions, formVariants, skipDatabase, dan patterns. Pada perintah artisan, --skip-actions dan --skip-routes memilih salah satu jenis output saja, --path memindahkan direktori hasil, sedangkan --with-form menambahkan varian form HTML. Ada juga --skip-database untuk mesin build tanpa akses database: Wayfinder membaca docblock @property pada model, dan binding tanpa docblock jatuh ke tipe string | number.
Memanggil Controller dari TypeScript
Misalnya ada InvoiceController dengan method show dan update. Setelah generate, pemanggilannya jadi seperti ini:
import { show, update } from "@/actions/App/Http/Controllers/InvoiceController";
import { show as showInvoice } from "@/routes/invoice";
show(42); // { url: "/invoices/42", method: "get" }
show.url(42); // "/invoices/42"
show.head(42); // { url: "/invoices/42", method: "head" }
update([42, 7]); // dua parameter: invoice dan termin
showInvoice("INV-001"); // named route, binding {invoice:number}
Wayfinder menyediakan method per verb HTTP di objek hasil generate. Kalau kamu hanya butuh URL untuk atribut href, pakai .url() supaya tidak membuat objek baru. Kalau controllernya invokable, fungsinya bisa dipanggil langsung tanpa nama method.
Satu jebakan kecil: kalau nama method di controller sama dengan reserved word JavaScript seperti delete atau import, Wayfinder menambahkan sufiks Method sehingga menjadi deleteMethod. Ini bukan bug, tapi konsekuensi sintaks JavaScript.
Bentuk Argumen dan Route Model Binding
Parameter bisa dikirim sebagai nilai tunggal, array berurutan, atau objek. Kalau route memakai binding kolom tertentu, misalnya /invoices/{invoice:number}, kamu bisa mengirim nilainya langsung atau lewat properti objek yang sesuai nama kolomnya — show("INV-001") dan show({ number: "INV-001" }) menghasilkan URL yang sama.
Inilah bagian yang paling terasa bedanya dibanding menulis URL manual. Kalau binding di route diganti dari id ke slug, TypeScript akan protes di tempat pemanggilan, bukan di production.
Named Route Lebih Stabil daripada Path Controller
Impor dari @/actions/... bergantung pada namespace controller. Kalau controller dipindah folder atau dipecah, path impor ikut berubah. Untuk halaman yang jarang berubah, impor dari @/routes/... lebih tahan lama karena mengikuti nama route, bukan struktur file.
Ada satu kasus yang perlu diketahui: bila dua route menunjuk method controller yang sama, Wayfinder tidak bisa menebak URL mana yang dimaksud dari nama action. Ekspornya berubah menjadi objek dengan key berupa URI, jadi kamu memilih sendiri, misalnya index["/clients/{client}/payments"]({ client: 1 }). Kalau URI-nya sama tapi verb-nya beda, key-nya diberi awalan verb seperti "post /exports/{report}".
Query String, Form, dan Integrasi Inertia
import { show } from "@/routes/invoice";
import { store, update } from "@/actions/App/Http/Controllers/InvoiceController";
show.url(42, { query: { page: 2, sort: "due" } });
show.url(42, { mergeQuery: { page: 3, sort: null } });
<form {...update.form(42)}></form> {/* action /invoices/42?_method=PATCH */}
Opsi query menambahkan parameter ke URL hasil, sedangkan mergeQuery menggabungkan dengan query string yang sedang aktif di browser — berguna untuk filter dan pagination karena parameter lain tidak hilang. Nilai null atau undefined justru menghapus parameter tersebut dari URL akhir.
Untuk form konvensional, generate dengan --with-form lalu sebar atribut form-nya langsung seperti contoh di atas. Untuk Inertia, hasil Wayfinder bisa diberikan ke form.submit(store()) maupun ke komponen Link sebagai href, karena objeknya sudah memuat metode HTTP. Kalau aplikasimu mulai ramai, kombinasikan dengan Laravel Pulse untuk memantau performa aplikasi agar endpoint yang sering dipanggil frontend tetap terukur.
Catatan Produksi yang Sering Kelewat
- Jangan commit hasil generate. Direktori
actions,routes, danwayfinderdibangun ulang setiap build, jadi aman masuk.gitignore. Kalau di-commit, diff PR jadi penuh noise. - Route cache bisa membuat hasil generate basi. Wayfinder membaca route dari router yang aktif. Kalau
php artisan optimizejalan di akhir deploy, cache lama masih terpakai saat build berikutnya: route baru tidak muncul dan Vite gagal me-resolve modul. Jalankanphp artisan route:clearsebelumnpm run build. - Status paket masih beta. Dokumentasi resminya sendiri menyebut API bisa berubah sebelum v1.0.0. Kunci versi di
composer.jsondan baca changelog sebelum upgrade. - Hati-hati mengimpor satu controller utuh. Impor per method lebih ramah tree-shaking; mengimpor objek controller membuat semua action-nya ikut masuk bundle.
Kalau kamu memakai feature flag untuk merilis halaman baru bertahap, kombinasikan dengan Laravel Pennant supaya route yang belum siap tidak terekspos lebih dulu. Untuk proyek yang mulai memanggil model AI dari backend, pola Laravel AI SDK bisa jadi acuan struktur controllernya.
Kapan Sebaiknya Tidak Memakai Wayfinder
Untuk API yang dikonsumsi aplikasi mobile atau klien lain, kontrak yang lebih tepat adalah OpenAPI atau SDK klien. Dan proyek dengan lima route belum tentu butuh ini: satu langkah build tambahan untuk menghindari lima string URL adalah pertukaran yang buruk.
FAQ
Apakah Wayfinder butuh Inertia?
Tidak. Wayfinder hanya menghasilkan fungsi TypeScript berisi URL dan method. Inertia adalah konsumen paling nyaman karena menerima objek tersebut langsung, tapi React, Vue, atau Svelte biasa juga bisa memakai .url() untuk fetch.
Apakah file hasil generate harus di-commit?
Tidak perlu, dan sebaiknya jangan. File tersebut deterministik dari route yang ada, jadi menyimpannya di repo hanya menambah konflik merge. Pastikan pipeline CI menjalankan generate sebelum proses build frontend.
Kenapa fungsi hasil generate tidak bisa dipanggil?
Biasanya karena ada dua route atau lebih yang menunjuk method controller yang sama. Wayfinder mengubah ekspor menjadi objek ber-key URI supaya kamu memilih URL secara eksplisit. Solusi cepat: impor lewat named route di direktori routes.
Kesimpulan
Laravel Wayfinder memindahkan pengetahuan tentang route dari kepala developer ke tipe. Hasilnya bukan sekadar autocomplete: URL yang salah jadi error build, perubahan binding ketahuan lebih awal, dan frontend tidak lagi menyimpan salinan aturan backend. Biayanya satu paket Composer, satu plugin Vite, dan satu kebiasaan baru — menjalankan route:clear sebelum build produksi.
Kalau proyekmu masih Laravel 8 dengan frontend Blade, tidak ada yang mendesak. Tapi untuk aplikasi baru dengan Inertia dan TypeScript, memasang Wayfinder sejak awal jauh lebih murah daripada membereskan URL hardcode setahun kemudian.
