Wayfinder Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require laravel/wayfinder
   npm install -D @laravel/vite-plugin-wayfinder
   

2. Configure Vite (vite.config.js):

   import { wayfinder } from "@laravel/vite-plugin-wayfinder";
   
   export default defineConfig({
       plugins: [
           wayfinder(),
           // other plugins...
       ],
   });
   

3. Generate TypeScript Definitions:

   php artisan wayfinder:generate
   

   • Default output: resources/js/wayfinder/, resources/js/actions/, resources/js/routes/
   • Custom path: php artisan wayfinder:generate --path=custom/path

First Use Case

Call a Controller Action Directly:

import { show } from "@/actions/App/Http/Controllers/PostController";
show(1); // Returns { url: "/posts/1", method: "get" }

Implementation Patterns

1. Controller Action Integration

• Single Parameter:

  import { store } from "@/actions/App/Http/Controllers/PostController";
  store({ title: "Hello" }); // POST to `/posts`
  

• Multiple Parameters:

  import { update } from "@/actions/App/Http/Controllers/PostController";
  update([1, "published"]); // PATCH to `/posts/1?status=published`
  

• Named Parameters:

  import { show } from "@/actions/App/Http/Controllers/PostController";
  show({ slug: "my-post" }); // GET to `/posts/my-post`
  

2. Named Routes

import { show } from "@/routes/post"; // Assumes route named `post.show`
show(1); // GET to `/posts/1`

3. Query Parameters

import { index } from "@/actions/App/Http/Controllers/PostController";
index({ page: 1 }, { query: { sort: "desc" } });
// GET to `/posts?page=1&sort=desc`

4. Form Handling

import { store } from "@/actions/App/Http/Controllers/PostController";
<form {...store.form()}>
  {/* Auto-generates action="/posts" method="post" */}
</form>

5. Invokable Controllers

import StorePostController from "@/actions/App/Http/Controllers/StorePostController";
StorePostController(); // Direct invocation

6. Inertia Integration

import { useForm } from "@inertiajs/react";
import { store } from "@/actions/App/Http/Controllers/PostController";
const form = useForm({ title: "Test" });
form.submit(store()); // Auto-resolves to POST `/posts`

7. Dynamic URL Methods

import { show } from "@/actions/App/Http/Controllers/PostController";
show.url(1); // "/posts/1"
show.head(1); // { url: "/posts/1", method: "head" }

Gotchas and Tips

Pitfalls

1. Reserved Keywords:

   • Controller methods like delete or import become deleteMethod/importMethod in TypeScript.
   • Fix: Rename methods in Laravel or use the generated name in TypeScript.

2. Blade Views in Routes:

   • Wayfinder crashes if Blade views are rendered during generation.
   • Fix: Use php artisan wayfinder:generate --eager to pre-render views.

3. Query Parameter Conflicts:

   • mergeQuery may unintentionally override existing URL params.
   • Fix: Explicitly set null to remove params:

     { mergeQuery: { page: null } } // Removes `page` from URL
     

4. Namespace Collisions:

   • Repeated namespaces (e.g., App\Http\Controllers\Admin\PostController) cause barrel file conflicts.
   • Fix: Use --path to customize output structure.

5. Invokable Controllers:

   • Importing the entire controller prevents tree-shaking.
   • Fix: Import specific methods instead:

     import { store } from "@/actions/App/Http/Controllers/PostController";
     

Debugging Tips

• Verify Generation:

  php artisan wayfinder:generate --verbose
  

• Check Output: Inspect resources/js/wayfinder/ for generated files.
• Vite Dev Server: Run npm run dev to auto-generate on file changes.

Extension Points

1. Customize Output:
   • Override default paths in wayfinder.config.php:

     return [
         'paths' => [
             'actions' => 'custom/path/actions',
             'routes' => 'custom/path/routes',
         ],
     ];
     

2. Add Middleware:
   • Extend the WayfinderGenerator service to include middleware in TypeScript definitions.
3. Form Variants:
   • Generate form helpers with --with-form:

     php artisan wayfinder:generate --with-form
     

4. Dynamic URL Defaults:
   • Use url() helpers in controllers to define dynamic defaults:

     public function show($id) {
         return response()->json(['id' => $id]);
     }
     // Wayfinder generates: show(1) → `/posts/1`
     

Performance

• Exclude Directories: Use --skip-actions or --skip-routes to skip generation for specific parts.
• Gitignore: Add generated directories to .gitignore:

  /resources/js/wayfinder/
  /resources/js/actions/
  /resources/js/routes/