‏Wayfinder: آدرس‌های تایپ‌دار از لاراول تا React

Freek Van der Herten از تیم Spatie تو این پست تعریف می‌کنه که چرا Laravel Wayfinder برای تیمشون مهم شده. اونا دارن یه helpdesk به اسم There There با لاراول و Inertia (یعنی ابزاری که React رو مستقیم به کنترلرهای لاراول وصل می‌کنه بدون API جدا) می‌سازن و Wayfinder یکی از پکیج‌هاییه که بهش تکیه کردن.

مشکل از این‌جا شروع می‌شه که یه کد React پر می‌شه از رشته‌های URL، تو هر fetch و هر فرم و لینک. حالا اگه تو لاراول اسم یه route رو عوض کنی یا یه پارامتر اجباری بهش اضافه کنی، هیچی موقع کامپایل نمی‌شکنه. به گفتهٔ نویسنده، یا تو پروداکشن می‌فهمی یا وقتی یه هم‌تیمی روی دکمهٔ اشتباه کلیک کنه.

Wayfinder برای هر route اسم‌دار یه تابع می‌سازه که import می‌کنی و با .url() آدرس رو می‌گیری:

import {
    add as addTeamMember,
    remove as removeTeamMember,
} from '@/routes/app/settings/workspace/teams/members';

removeTeamMember.url({ team: team.ulid, user: member.ulid });

پارامترها type-check می‌شن، یعنی اگه پارامتر user رو به member تغییر بدی، TypeScript همهٔ جاهایی که صداش زدن رو پیدا می‌کنه. اسم routeها هم مستقیم به مسیر import تبدیل می‌شه، پس پیدا کردنشون با autocomplete کار ساده‌ایه.

برای هر کنترلر هم یه تابع تایپ‌دار ساخته می‌شه. تیم Spatie وقتی بیرون از Inertia با fetch معمولی به یه endpoint درخواست می‌زنه، از این استفاده می‌کنه، مثلاً MessageRetryController.url(...) برای تلاش دوباره روی یه پیام ناموفق. این‌جا هم اگه اسم کنترلر تو PHP عوض بشه، بیلد TypeScript می‌شکنه نه پروداکشن.

برای این‌که همه‌چی خودکار بمونه، پلاگین @laravel/vite-plugin-wayfinder به Vite اضافه می‌شه. این پلاگین موقع توسعه routeها و کنترلرها رو زیر نظر داره و هر وقت چیزی عوض بشه، توابع رو دوباره می‌سازه. نویسنده می‌گه Wayfinder یه دسته کامل از باگ‌ها رو براشون حذف کرده: دیگه نه لازمه موقع تغییر route کل کد رو grep کنی، نه سر ۴۰۴های عجیب یا اسلش آخر آدرس بحث کنی.

نکات کلیدی:

• Wayfinder برای هر route اسم‌دار و هر کنترلر لاراول یه تابع TypeScript تایپ‌دار می‌سازه
• آدرس با متد .url() و پارامترهای type-check‌شده ساخته می‌شه
• تغییر اسم route، پارامتر یا کنترلر تو PHP، بیلد TypeScript رو می‌شکنه
• پلاگین @laravel/vite-plugin-wayfinder توابع رو موقع توسعه خودکار به‌روز می‌کنه
• Spatie ازش تو helpdesk جدیدش There There (لاراول + Inertia) استفاده می‌کنه