Skip to content

Commit f4fbd65

Browse files
pushpak1300joetannenbaumtaylorotwell
authored
Add wayfinder guidelines (#327)
* Add Wayfinder package support and guidelines Signed-off-by: Pushpak Chhajed <[email protected]> * Fix code styling * Update core.blade.php Signed-off-by: Pushpak Chhajed <[email protected]> * Update tests Signed-off-by: Pushpak Chhajed <[email protected]> * Update Test Signed-off-by: Pushpak Chhajed <[email protected]> * Update core.blade.php * Update core.blade.php --------- Signed-off-by: Pushpak Chhajed <[email protected]> Co-authored-by: Joe Tannenbaum <[email protected]> Co-authored-by: Taylor Otwell <[email protected]>
1 parent a33c754 commit f4fbd65

File tree

3 files changed

+238
-2
lines changed

3 files changed

+238
-2
lines changed

‎.ai/wayfinder/core.blade.php‎

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
@php
2+
/** @var \Laravel\Boost\Install\GuidelineAssist $assist */
3+
@endphp
4+
## Laravel Wayfinder
5+
6+
Wayfinder generates TypeScript functions and types for Laravel controllers and routes which you can import into your client side code. It provides type safety and automatic synchronization between backend routes and frontend code.
7+
8+
### Development Guidelines
9+
- Always use `search-docs` to check wayfinder correct usage before implementing any features.
10+
- Always Prefer named imports for tree-shaking (e.g., `import { show } from '@/actions/...'`)
11+
- Avoid default controller imports (prevents tree-shaking)
12+
- Run `wayfinder:generate` after route changes if Vite plugin isn't installed
13+
14+
### Feature Overview
15+
- Form Support: Use `.form()` with `--with-form` flag for HTML form attributes — `<form {...store.form()}>` → `action="/posts" method="post"`
16+
- HTTP Methods: Call `.get()`, `.post()`, `.patch()`, `.put()`, `.delete()` for specific methods — `show.head(1)` → `{ url: "/posts/1", method: "head" }`
17+
- Invokable Controllers: Import and invoke directly as functions. For example, `import StorePost from '@/actions/.../StorePostController'; StorePost()`
18+
- Named Routes: Import from `@/routes/` for non-controller routes. For example, `import { show } from '@/routes/post'; show(1)` for route name `post.show`
19+
- Parameter Binding: Detects route keys (e.g., `{post:slug}`) and accepts matching object properties — `show("my-post")` or `show({ slug: "my-post" })`
20+
- Query Merging: Use `mergeQuery` to merge with `window.location.search`, set values to `null` to remove — `show(1, { mergeQuery: { page: 2, sort: null } })`
21+
- Query Parameters: Pass `{ query: {...} }` in options to append params — `show(1, { query: { page: 1 } })` → `"/posts/1?page=1"`
22+
- Route Objects: Functions return `{ url, method }` shaped objects — `show(1)` → `{ url: "/posts/1", method: "get" }`
23+
- URL Extraction: Use `.url()` to get URL string — `show.url(1)` → `"/posts/1"`
24+
25+
### Example Usage
26+
@verbatim
27+
<code-snippet name="Wayfinder Basic Usage" lang="typescript">
28+
// Import controller methods (tree-shakable)
29+
import { show, store, update } from '@/actions/App/Http/Controllers/PostController'
30+
31+
// Get route object with URL and method...
32+
show(1) // { url: "/posts/1", method: "get" }
33+
34+
// Get just the URL...
35+
show.url(1) // "/posts/1"
36+
37+
// Use specific HTTP methods...
38+
show.get(1) // { url: "/posts/1", method: "get" }
39+
show.head(1) // { url: "/posts/1", method: "head" }
40+
41+
// Import named routes...
42+
import { show as postShow } from '@/routes/post' // For route name 'post.show'
43+
postShow(1) // { url: "/posts/1", method: "get" }
44+
</code-snippet>
45+
@endverbatim
46+
47+
@if($assist->roster->uses(\Laravel\Roster\Enums\Packages::INERTIA_LARAVEL) || $assist->roster->uses(\Laravel\Roster\Enums\Packages::INERTIA_REACT) || $assist->roster->uses(\Laravel\Roster\Enums\Packages::INERTIA_VUE) || $assist->roster->uses(\Laravel\Roster\Enums\Packages::INERTIA_SVELTE))
48+
### Wayfinder + Inertia
49+
@if($assist->inertia()->hasFormComponent())
50+
If your application uses the `<Form>` component from Inertia, you can use Wayfinder to generate form action and method automatically.
51+
@if($assist->roster->uses(\Laravel\Roster\Enums\Packages::INERTIA_REACT))
52+
@boostsnippet("Wayfinder Form Component (React)", "typescript")
53+
<Form {...store.form()}><input name="title" /></Form>
54+
@endboostsnippet
55+
@endif
56+
@if($assist->roster->uses(\Laravel\Roster\Enums\Packages::INERTIA_VUE))
57+
@boostsnippet("Wayfinder Form Component (Vue)", "vue")
58+
<Form v-bind="store.form()"><input name="title" /></Form>
59+
@endboostsnippet
60+
@endif
61+
@if($assist->roster->uses(\Laravel\Roster\Enums\Packages::INERTIA_SVELTE))
62+
@boostsnippet("Wayfinder Form Component (Svelte)", "svelte")
63+
<Form {...store.form()}><input name="title" /></Form>
64+
@endboostsnippet
65+
@endif
66+
@else
67+
If your application uses the `useForm` component from Inertia, you can directly submit to the wayfinder generated functions.
68+
69+
<code-snippet name="Wayfinder useForm Example" lang="typescript">
70+
import { store } from "@/actions/App/Http/Controllers/ExampleController";
71+
72+
const form = useForm({
73+
name: "My Big Post",
74+
});
75+
76+
form.submit(store());
77+
</code-snippet>
78+
@endif
79+
@endif

‎all.php‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -54,6 +54,7 @@ public function packages(): \Laravel\Roster\PackageCollection
5454
'folio' => \Laravel\Roster\Enums\Packages::FOLIO,
5555
'pennant' => \Laravel\Roster\Enums\Packages::PENNANT,
5656
'tailwindcss' => \Laravel\Roster\Enums\Packages::TAILWINDCSS,
57+
'wayfinder' => \Laravel\Roster\Enums\Packages::WAYFINDER,
5758
];
5859

5960
if (isset($enumMapping[$packageName])) {

‎tests/Feature/Install/GuidelineComposerTest.php‎

Lines changed: 158 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,6 @@
2323
$this->herd = Mockery::mock(Herd::class);
2424
$this->herd->shouldReceive('isInstalled')->andReturn(false)->byDefault();
2525

26-
// Bind the mock to the service container so it's used everywhere
2726
$this->app->instance(Roster::class, $this->roster);
2827

2928
$this->composer = new GuidelineComposer($this->roster, $this->herd);
@@ -37,7 +36,6 @@
3736
]);
3837

3938
$this->roster->shouldReceive('packages')->andReturn($packages);
40-
// Mock all Inertia package version checks
4139
$this->roster->shouldReceive('usesVersion')
4240
->with(Packages::INERTIA_LARAVEL, '2.1.0', '>=')
4341
->andReturn($shouldIncludeForm);
@@ -432,3 +430,161 @@
432430
->not->toContain('volt-anonymous-fragment')
433431
->not->toContain('@livewire');
434432
});
433+
434+
test('includes wayfinder guidelines with inertia integration when both packages are present', function (): void {
435+
$packages = new PackageCollection([
436+
new Package(Packages::LARAVEL, 'laravel/framework', '11.0.0'),
437+
new Package(Packages::WAYFINDER, 'laravel/wayfinder', '1.0.0'),
438+
new Package(Packages::INERTIA_REACT, 'inertiajs/inertia-react', '2.1.2'),
439+
new Package(Packages::INERTIA_LARAVEL, 'inertiajs/inertia-laravel', '2.1.2'),
440+
]);
441+
442+
$this->roster->shouldReceive('packages')->andReturn($packages);
443+
444+
$this->roster->shouldReceive('uses')->with(Packages::INERTIA_LARAVEL)->andReturn(true);
445+
$this->roster->shouldReceive('uses')->with(Packages::INERTIA_REACT)->andReturn(true);
446+
$this->roster->shouldReceive('uses')->with(Packages::INERTIA_VUE)->andReturn(false);
447+
$this->roster->shouldReceive('uses')->with(Packages::INERTIA_SVELTE)->andReturn(false);
448+
449+
$this->roster->shouldReceive('usesVersion')
450+
->with(Packages::INERTIA_LARAVEL, Mockery::any(), '>=')
451+
->andReturn(true);
452+
$this->roster->shouldReceive('usesVersion')
453+
->with(Packages::INERTIA_REACT, Mockery::any(), '>=')
454+
->andReturn(true);
455+
$this->roster->shouldReceive('usesVersion')
456+
->with(Packages::INERTIA_VUE, Mockery::any(), '>=')
457+
->andReturn(false);
458+
$this->roster->shouldReceive('usesVersion')
459+
->with(Packages::INERTIA_SVELTE, Mockery::any(), '>=')
460+
->andReturn(false);
461+
462+
$guidelines = $this->composer->compose();
463+
464+
expect($guidelines)
465+
->toContain('=== wayfinder/core rules ===')
466+
->toContain('Wayfinder + Inertia')
467+
->toContain('Wayfinder Form Component (React)')
468+
->toContain('<Form {...store.form()}>')
469+
->toContain('## Laravel Wayfinder')
470+
->not->toContain('Wayfinder Form Component (Vue)')
471+
->not->toContain('Wayfinder Form Component (Svelte)')
472+
->not->toContain('<Form v-bind="store.form()">');
473+
});
474+
475+
test('includes wayfinder guidelines with inertia vue integration', function (): void {
476+
$packages = new PackageCollection([
477+
new Package(Packages::LARAVEL, 'laravel/framework', '11.0.0'),
478+
new Package(Packages::WAYFINDER, 'laravel/wayfinder', '1.0.0'),
479+
new Package(Packages::INERTIA_VUE, 'inertiajs/inertia-vue', '2.1.2'),
480+
new Package(Packages::INERTIA_LARAVEL, 'inertiajs/inertia-laravel', '2.1.2'),
481+
]);
482+
483+
$this->roster->shouldReceive('packages')->andReturn($packages);
484+
485+
$this->roster->shouldReceive('uses')->with(Packages::INERTIA_LARAVEL)->andReturn(true);
486+
$this->roster->shouldReceive('uses')->with(Packages::INERTIA_REACT)->andReturn(false);
487+
$this->roster->shouldReceive('uses')->with(Packages::INERTIA_VUE)->andReturn(true);
488+
$this->roster->shouldReceive('uses')->with(Packages::INERTIA_SVELTE)->andReturn(false);
489+
490+
$this->roster->shouldReceive('usesVersion')
491+
->with(Packages::INERTIA_LARAVEL, Mockery::any(), '>=')
492+
->andReturn(true);
493+
$this->roster->shouldReceive('usesVersion')
494+
->with(Packages::INERTIA_REACT, Mockery::any(), '>=')
495+
->andReturn(false);
496+
$this->roster->shouldReceive('usesVersion')
497+
->with(Packages::INERTIA_VUE, Mockery::any(), '>=')
498+
->andReturn(true);
499+
$this->roster->shouldReceive('usesVersion')
500+
->with(Packages::INERTIA_SVELTE, Mockery::any(), '>=')
501+
->andReturn(false);
502+
503+
$guidelines = $this->composer->compose();
504+
505+
expect($guidelines)
506+
->toContain('=== wayfinder/core rules ===')
507+
->toContain('Wayfinder + Inertia')
508+
->toContain('Wayfinder Form Component (Vue)')
509+
->toContain('<Form v-bind="store.form()">')
510+
->toContain('## Laravel Wayfinder')
511+
->not->toContain('Wayfinder Form Component (React)')
512+
->not->toContain('Wayfinder Form Component (Svelte)');
513+
});
514+
515+
test('includes wayfinder guidelines with inertia svelte integration', function (): void {
516+
$packages = new PackageCollection([
517+
new Package(Packages::LARAVEL, 'laravel/framework', '11.0.0'),
518+
new Package(Packages::WAYFINDER, 'laravel/wayfinder', '1.0.0'),
519+
new Package(Packages::INERTIA_SVELTE, 'inertiajs/inertia-svelte', '2.1.2'),
520+
new Package(Packages::INERTIA_LARAVEL, 'inertiajs/inertia-laravel', '2.1.2'),
521+
]);
522+
523+
$this->roster->shouldReceive('packages')->andReturn($packages);
524+
525+
$this->roster->shouldReceive('uses')->with(Packages::INERTIA_LARAVEL)->andReturn(true);
526+
$this->roster->shouldReceive('uses')->with(Packages::INERTIA_REACT)->andReturn(false);
527+
$this->roster->shouldReceive('uses')->with(Packages::INERTIA_VUE)->andReturn(false);
528+
$this->roster->shouldReceive('uses')->with(Packages::INERTIA_SVELTE)->andReturn(true);
529+
530+
$this->roster->shouldReceive('usesVersion')
531+
->with(Packages::INERTIA_LARAVEL, Mockery::any(), '>=')
532+
->andReturn(true);
533+
$this->roster->shouldReceive('usesVersion')
534+
->with(Packages::INERTIA_REACT, Mockery::any(), '>=')
535+
->andReturn(false);
536+
$this->roster->shouldReceive('usesVersion')
537+
->with(Packages::INERTIA_VUE, Mockery::any(), '>=')
538+
->andReturn(false);
539+
$this->roster->shouldReceive('usesVersion')
540+
->with(Packages::INERTIA_SVELTE, Mockery::any(), '>=')
541+
->andReturn(true);
542+
543+
$guidelines = $this->composer->compose();
544+
545+
expect($guidelines)
546+
->toContain('=== wayfinder/core rules ===')
547+
->toContain('Wayfinder + Inertia')
548+
->toContain('Wayfinder Form Component (Svelte)')
549+
->toContain('<Form {...store.form()}>')
550+
->toContain('## Laravel Wayfinder')
551+
->not->toContain('Wayfinder Form Component (React)')
552+
->not->toContain('Wayfinder Form Component (Vue)')
553+
->not->toContain('<Form v-bind="store.form()">');
554+
});
555+
556+
test('includes wayfinder guidelines without inertia integration when inertia is not present', function (): void {
557+
$packages = new PackageCollection([
558+
new Package(Packages::LARAVEL, 'laravel/framework', '11.0.0'),
559+
new Package(Packages::WAYFINDER, 'laravel/wayfinder', '1.0.0'),
560+
]);
561+
562+
$this->roster->shouldReceive('packages')->andReturn($packages);
563+
564+
$this->roster->shouldReceive('uses')->with(Packages::INERTIA_LARAVEL)->andReturn(false);
565+
$this->roster->shouldReceive('uses')->with(Packages::INERTIA_REACT)->andReturn(false);
566+
$this->roster->shouldReceive('uses')->with(Packages::INERTIA_VUE)->andReturn(false);
567+
$this->roster->shouldReceive('uses')->with(Packages::INERTIA_SVELTE)->andReturn(false);
568+
569+
$this->roster->shouldReceive('usesVersion')
570+
->with(Packages::INERTIA_LARAVEL, Mockery::any(), '>=')
571+
->andReturn(false);
572+
$this->roster->shouldReceive('usesVersion')
573+
->with(Packages::INERTIA_REACT, Mockery::any(), '>=')
574+
->andReturn(false);
575+
$this->roster->shouldReceive('usesVersion')
576+
->with(Packages::INERTIA_VUE, Mockery::any(), '>=')
577+
->andReturn(false);
578+
$this->roster->shouldReceive('usesVersion')
579+
->with(Packages::INERTIA_SVELTE, Mockery::any(), '>=')
580+
->andReturn(false);
581+
582+
$guidelines = $this->composer->compose();
583+
584+
expect($guidelines)
585+
->toContain('=== wayfinder/core rules ===')
586+
->toContain('## Laravel Wayfinder')
587+
->toContain('import { show } from \'@/actions/')
588+
->not->toContain('Wayfinder + Inertia')
589+
->not->toContain('Wayfinder Form Component');
590+
});

0 commit comments

Comments
 (0)