Wayfinder Laravel Package

Product Decisions This Supports

• Eliminate API contract drift: Automatically sync Laravel routes/actions with TypeScript frontend, reducing manual URL/endpoint management and API documentation overhead.
• Accelerate frontend development: Enable developers to call backend endpoints as first-class TypeScript functions (e.g., showPost(1) instead of axios.get('/posts/1')), improving DX and reducing boilerplate.
• Enhance form handling: Generate form attributes (e.g., action, method) directly from backend routes, ensuring consistency between frontend forms and backend logic.
• Inertia.js integration: Seamlessly integrate with Inertia’s useForm and Link components, enabling zero-config form submissions and navigation.
• Build vs. buy: Buy—avoids reinventing route-to-TypeScript mapping logic, leveraging Laravel’s ecosystem for maintainability.
• Roadmap priorities:
  • Phase 1: Adopt for core CRUD endpoints to reduce frontend-backend misalignment.
  • Phase 2: Extend to complex routes (e.g., nested resources, dynamic segments) and integrate with testing frameworks (e.g., generate mocks from Wayfinder types).
  • Phase 3: Explore server-side rendering (SSR) compatibility (e.g., Next.js) for hybrid setups.

When to Consider This Package

• Adopt if:
  • Your stack uses Laravel + TypeScript/Vite (or Inertia.js).
  • Frontend-backend communication relies on hardcoded URLs or manual API specs (e.g., OpenAPI).
  • Teams struggle with route changes breaking frontend or vice versa.
  • You prioritize developer velocity over minimal setup (e.g., willing to trade minor runtime overhead for DX gains).
• Look elsewhere if:
  • Your backend isn’t Laravel (e.g., Django, Node.js/Express).
  • You use GraphQL or a strictly decoupled architecture (e.g., separate frontend/backend repos with no shared codegen).
  • Your team prefers runtime API clients (e.g., OpenAPI-generated SDKs) over compile-time route binding.
  • You’re in early-stage prototyping where route stability is low (Wayfinder adds build-step dependency).
  • Your project uses non-TypeScript frontends (e.g., React Native, Vue 2).

How to Pitch It (Stakeholders)

For Executives:

"Wayfinder eliminates a major friction point in our Laravel + TypeScript workflow: manual API contract management. Today, every route change requires frontend updates—Wayfinder automates this by generating TypeScript functions for every Laravel endpoint. This reduces bugs from URL mismatches, speeds up development (e.g., deletePost(1) instead of axios.delete('/posts/1')), and aligns our frontend with backend changes in real-time. For Inertia.js apps, it also simplifies form submissions and navigation. The tradeoff is a minor build-step dependency, but the payoff is fewer production issues and faster iteration—especially as our API grows."

ROI:

• Dev time saved: ~30% reduction in frontend-backend sync work.
• Risk reduction: Zero risk of broken URLs due to route renames.
• Scalability: Future-proofs as we add more endpoints.

For Engineering:

*"Wayfinder solves two key pain points:

1. No more stringly-typed API calls: Every Laravel route/action becomes a fully typed TypeScript function with autocompletion, parameter validation, and method support (GET/PATCH/DELETE/etc.).
2. Seamless form integration: Generate <form> attributes (e.g., action, method) directly from backend routes, ensuring consistency.

How it works:

• Run php artisan wayfinder:generate to create TypeScript stubs in resources/js/wayfinder/.
• Import and use like this:

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

• Inertia.js bonus: Works out-of-the-box with useForm and Link components.

Tradeoffs:

• Build dependency: Requires Vite plugin for dev-time updates.
• Beta stage: API may stabilize before v1.0 (monitor changelog).
• Not a replacement for: Runtime API clients (e.g., OpenAPI) or GraphQL.

Next steps:

1. Pilot on a non-critical module (e.g., blog posts).
2. Integrate with our CI/CD to auto-generate types on deploy.
3. Explore extending for testing (e.g., generate mocks from Wayfinder types)."*