Wayfinder Laravel Package

Product Decisions This Supports

• Build vs. Buy: Buy – Eliminates manual API client maintenance (e.g., OpenAPI/Swagger, Axios interceptors, or custom route resolvers). Reduces technical debt by auto-generating TypeScript definitions from Laravel routes/controllers, ensuring frontend/backend parity.
• Developer Experience (DX): Accelerates frontend development by providing zero-friction API access—no more hardcoded URLs, manual route syncing, or runtime errors from stale API specs. Enables tree-shakable imports (e.g., import { show } from "@/actions/PostController").
• Roadmap Prioritization:
  • Phase 1: Integrate into new Laravel/Inertia projects to replace manual API clients (e.g., Axios + OpenAPI).
  • Phase 2: Extend to legacy projects via a migration path (e.g., hybrid OpenAPI + Wayfinder).
  • Phase 3: Leverage Wayfinder for form submissions (conventional HTML/Inertia) and real-time updates (e.g., Laravel Echo + Wayfinder-generated WebSocket routes).
• Use Cases:
  • Full-stack Laravel/Inertia apps: Replace route() helpers with typed, importable functions.
  • Microservices: Generate client-side stubs for Laravel microservices consumed by React/Vue.
  • Admin panels: Auto-generate CRUD API calls from Laravel controllers (e.g., Nova-like interfaces).
  • Edge cases: Handle named routes, query parameters, and multi-route actions (e.g., /posts/{id} vs. /posts/{slug}).

When to Consider This Package

Adopt Wayfinder If:

✅ Your stack is Laravel + TypeScript/React/Vue: Wayfinder is Laravel-native and assumes a Laravel backend with a modern frontend toolchain (Vite, Inertia, or standalone TS). ✅ You’re tired of API drift: Manual API clients (e.g., OpenAPI) often fall out of sync with backend changes. Wayfinder auto-generates types from your routes/controllers. ✅ You use Inertia.js: Seamless integration with useForm().submit(wayfinderAction()) and Link components. ✅ Your team values DX: Reduces context-switching between frontend/backend by providing IDE-friendly imports (autocomplete, type safety). ✅ You need query parameter control: Supports merging/replacing query params at runtime (e.g., pagination, sorting).

Look Elsewhere If:

❌ You’re not using Laravel: Wayfinder is Laravel-specific (routes, controllers, Blade). For non-Laravel backends, use OpenAPI/Swagger or tRPC. ❌ Your frontend is vanilla JS: Wayfinder generates TypeScript. For JS-only projects, consider manual route resolvers or fetch-based utilities. ❌ You need WebSocket support: Wayfinder focuses on HTTP routes. For real-time, pair with Laravel Echo or tRPC. ❌ You’re in a monorepo with non-Laravel services: Wayfinder won’t generate clients for Node.js/Go/Python services. ❌ You require strict API versioning: Wayfinder is runtime-generated—not ideal for versioned APIs (use OpenAPI instead). ❌ Your team resists tooling: Wayfinder adds a build step (wayfinder:generate). Teams preferring "no dependencies" may reject it.

How to Pitch It (Stakeholders)

For Executives (Business/Tech Leads)

"Wayfinder eliminates a $50K/year technical debt sinkhole."

• Problem: Your frontend team spends 20% of dev time maintaining API clients (OpenAPI, Axios interceptors, route resolvers). Backend changes break frontend integrations, requiring manual syncs.
• Solution: Wayfinder auto-generates TypeScript API clients from your Laravel routes/controllers. No more guessing URLs or syncing specs—100% parity between backend and frontend.
• ROI:
  • Dev velocity: Frontend devs call Laravel endpoints like local functions (e.g., showPost(1) instead of axios.get('/posts/1')).
  • Reduced bugs: TypeScript catches route parameter errors at compile time.
  • Scalability: Add a new Laravel route? The frontend auto-updates—no API docs or PRs needed.
• Risk: Low. Wayfinder is MIT-licensed, Laravel-backed, and integrates with Inertia (your existing stack). Beta phase ends with v1.0.

For Engineers (Dev/Architects)

"Wayfinder turns Laravel routes into first-class TypeScript citizens."

• Key Benefits:
  • Zero-boilerplate API calls: Import and invoke Laravel controllers directly:

    import { store } from "@/actions/PostController";
    store({ title: "Hello" }); // POSTs to `/posts` with type safety.
    

  • Inertia superpowers: Works seamlessly with useForm().submit(store()) and Link components.
  • Query param control: Merge/replace URL params at runtime:

    show(1, { query: { page: 2 } }); // `/posts/1?page=2`
    

  • Form support: Generate <form> attributes dynamically:

    <form {...update.form(1)}> {/* action="/posts/1?_method=PATCH" */}
    

• Migration Path:
  • Start with critical paths (e.g., checkout flows, admin CRUD).
  • Use --skip-actions to opt-in gradually.
  • Pair with Vite’s HMR for instant feedback during development.
• Trade-offs:
  • Build dependency: Adds wayfinder:generate to your deploy pipeline (mitigated by route:clear).
  • Beta risks: API may stabilize before v1.0 (monitor changelog).
  • Not a replacement for OpenAPI: Use OpenAPI for public APIs; Wayfinder for internal Laravel services.

For Frontend Teams

"No more ‘Works on my machine’ API errors."

• Pain Points Solved:
  • Stale API docs: Wayfinder types are always in sync with your Laravel codebase.
  • Route parameter hell: Pass objects or arrays—Wayfinder handles the rest:

    update({ post: { id: 1 }, author: { id: 2 } }); // `/posts/1?author=2`
    

  • IDE happiness: Autocomplete for routes, controllers, and parameters.
  • Form magic: Generate <form> attributes with one line:

    <form {...store.form()}> {/* action="/posts" method="post" */}
    

• Getting Started:
  1. Install: composer require laravel/wayfinder + npm i -D @laravel/vite-plugin-wayfinder.
  2. Add to vite.config.js: plugins: [wayfinder()].
  3. Run php artisan wayfinder:generate (or let Vite handle it in dev).
  4. Import and use:

     import { show } from "@/actions/PostController";
     show(1).url; // "/posts/1"