Що таке Laravel Wayfinder і як він типізує маршрути у фронтенді?

Фронтенд Laravel-застосунку постійно будує URL: /posts/${id}, /api/vacancies?page=2. Рядкові шляхи ламаються непомітно - маршрут перейменували в routes/web.php, а у фронтенді лишився старий.

Wayfinder генерує з маршрутів і контролерів Laravel типізовані TypeScript-функції:

composer require laravel/wayfinder
npm i -D @laravel/vite-plugin-wayfinder
php artisan wayfinder:generate

// vite.config.ts
import { wayfinder } from '@laravel/vite-plugin-wayfinder';

export default defineConfig({ plugins: [wayfinder() /* ... */] });

Плагін перегенеровує файли під час збирання й при зміні маршрутів чи контролерів у режимі розробки.

Використання - дії контролерів:

import { show, update } from '@/actions/App/Http/Controllers/PostController';

show(1);              // { url: '/posts/1', method: 'get' }
show.url(1);          // '/posts/1'
update({ post: 1 });  // { url: '/posts/1', method: 'put' }

Названі маршрути:

import { show } from '@/routes/post';   // маршрут post.show
show(1).url;

Що дає:

• помилка компіляції при зміні маршруту: видалили метод контролера чи змінили параметри - TypeScript покаже кожне місце використання;
• правильний HTTP-метод разом з URL - не треба пам'ятати, PUT чи PATCH;
• параметри з прив'язкою моделей: приймає id, об'єкт { id } чи ключ ({ slug }), якщо маршрут задає {post:slug};
• форми: з --with-form - атрибути для <form> ({...store.form()}), включно з підміною методу.

У стартових наборах Laravel з React і Vue Wayfinder уже налаштовано, і з Inertia він використовується для Link та router.visit.

Що варто знати:

• згенеровані каталоги (resources/js/actions, routes, wayfinder) можна не зберігати в Git - вони повністю створюються заново при збиранні;
• кешовані маршрути при деплої: якщо route:cache лишився від попереднього релізу, генерація візьме старі маршрути - перед збиранням фронтенду потрібен route:clear;
• Wayfinder типізує URL і параметри маршруту, але не тіло запиту й відповідь - для них потрібні окремі типи (DTO, OpenAPI);
• пакет на момент написання в бета-версії - API може змінюватися до 1.0.

Попередник - Ziggy (функція route('post.show', id) у JavaScript), але без повної типізації за маршрутами.

Докладніше в документації: Laravel Wayfinder