If you've been looking for a way to bridge the gap between your PHP backend and JavaScript/TypeScript frontend, the new Laravel Wayfinder is the open source tool you've been waiting for.
Laravel’s own Joe Tannenbaum (Engineering Team Lead for the Open Source Team) and Leah Thompson (DevRel Engineer) recently hosted a live stream to showcase Wayfinder’s next-generation capabilities and two of its underlying packages: Ranger and Surveyor.
Read on for a snapshot of their conversation, or watch the entire stream.
The Problem Wayfinder Solves
Building modern web applications often means writing PHP on the backend and JavaScript or TypeScript on the frontend. These two sides of your application can't naturally share data types, enums, validation rules, or other structures. If you're using a framework like Inertia.js or maintaining separate repositories for your Laravel API and single-page application, keeping everything in sync becomes a manual, error-prone process.
Wayfinder changes that. It analyzes your Laravel application and automatically generates TypeScript equivalents for routes, validation rules, models, enums, broadcast events, environment variables, and more. The result is end-to-end type safety between your PHP and TypeScript code, with autocomplete and type checking built right in.
What's Under the Hood: Surveyor and Ranger
The current version of Wayfinder (included in Laravel's Starter Kits) handles route generation. The new version, currently in public beta, is now available and goes much further. To make this possible, the team built two foundational libraries.
Surveyor
Surveyor performs static analysis on your Laravel application. It examines your controllers, models, broadcast events, and other classes to extract detailed information about their structure, methods, properties, and return types. While it's primarily a static analysis tool, it also inspects specific parts of your application, like app bindings and models, to get a complete picture.
Ranger
Ranger sits on top of Surveyor and transforms its results into clean, consumable data transfer objects (DTOs). It takes the comprehensive analysis from Surveyor and delivers back a structured format that's easy to work with. Think of it as the translation layer that makes sense of all the information Surveyor collects.
Wayfinder listens to Ranger and converts those DTOs into TypeScript. When Ranger finds a route, model, or broadcast channel, it passes that information to Wayfinder, which then generates the corresponding TypeScript code. Both Surveyor and Ranger can be used independently in other projects, but they form the foundation of Wayfinder.
What You Can Do with Wayfinder
During the live stream, Joe demonstrated how Wayfinder transforms everyday development tasks. Here's what you can expect:
Automatic Route Generation
Instead of hardcoding URLs in your frontend code, Wayfinder generates type-safe route helpers. When you change a route in your Laravel application, your frontend code automatically updates. You get full autocomplete for route parameters and methods, and if you reference a route that doesn't exist, you'll see an error immediately.
Model Attributes and Properties
When you pass Eloquent models through Inertia props, Wayfinder analyzes your models and generates TypeScript types for all their attributes, relationships, and accessors. Add a new attribute to your model, and it immediately appears in your TypeScript autocomplete. The more specific your PHP types are, the more accurate your generated TypeScript types will be.
Form Validation Rules
Form requests and validation rules in your Laravel controllers can be extracted and converted into TypeScript types. This means your frontend forms can use the exact same validation structure as your backend. When you update validation rules in PHP, those changes flow through to your TypeScript code, keeping both sides perfectly aligned.
Broadcast Events and Channels
If you're using Laravel Echo, Wayfinder generates autocomplete for your broadcast channel names and event names. Even better, it infers the payload structure from your broadcast events, so you get type safety on the data coming through your WebSocket connections. No more guessing what properties are available on incoming events.
Enums
PHP enums are converted to TypeScript enums automatically. If you're casting a model attribute to an enum and need to display those values in a select dropdown on your frontend, Wayfinder keeps both sides in sync. Add a new enum case, and it appears in your TypeScript code immediately.
Environment Variables
Wayfinder analyzes your .env file and generates TypeScript types for environment variables, including their correct data types (boolean, string, number). You'll get autocomplete when accessing environment variables from your frontend code.
Inertia Shared Props
When you define shared props in your HandleInertiaRequests middleware, Wayfinder automatically generates the corresponding TypeScript types. These props appear in your page component types without any manual configuration. If you enable the withAllErrors option in Inertia, Wayfinder even updates the error type from a single string to an array of strings.
Cross-Repository Synchronization
One of the most impressive features demonstrated during the stream is what Joe calls "jumping the fence." If your Laravel API and frontend application live in separate repositories, Wayfinder can automatically create pull requests from your API repository to your frontend repository whenever types change.
Here's how it works: You make changes to your Laravel API (updating routes, adding model attributes, modifying enums, etc.). A GitHub Action triggers in your API repository, generates the updated Wayfinder types, and creates a pull request in your frontend repository with the changes. You review the PR to ensure everything looks correct, merge it, and your frontend code is now in sync with your API. You don’t need to manually copy type definitions, and there’s no chance of forgetting to update both sides.
During the live demo, Joe changed a route endpoint from "catalog" to "catalogs" in the Laravel API and added a new "Jurassic World" case to a theme enum. Within seconds, a pull request appeared in the frontend repository with both changes. After merging and pulling the updates, the frontend application automatically used the new route without touching a single line of frontend code.
Current Status and What's Next for Wayfinder
The current version of Wayfinder, which handles route generation, is stable and included in Laravel's Starter Kits. The new version is much more ambitious. It's what Joe describes as an "uppercase B beta," meaning there's still work to be done, but it's ready for developers to start testing in their projects.
The team is actively working on several improvements:
- Better support for classes that implement
ArrayableandJsonableinterfaces, which will improve handling of Eloquent resources and Spatie's Laravel Data package. - Performance optimizations for larger applications. While small to medium-sized apps work well, some larger codebases experience memory and speed issues during type generation.
- More accurate type inference for complex scenarios, particularly with Eloquent collections.
- Potential support for translations, making it easier to share Laravel's translation strings with frontend code.
Getting Started
If you want to try the next version of Wayfinder, you can install it like this:
1composer require laravel/wayfinder:dev-nextThe Wayfinder repository includes detailed upgrade instructions in a banner at the top of the GitHub README. For developers using the current stable version in Laravel's Starter Kits, the upgrade process involves a few configuration changes but is well documented.
The team is actively seeking feedback on performance issues, type accuracy, and use cases that may not work as expected. If you encounter issues or have suggestions for improvement, the best place to report them is the GitHub repository rather than social media, where they're more likely to be tracked and addressed.
Keep Your Frontend and Backend in Sync
Wayfinder eliminates one of the biggest pain points of full stack development: keeping your backend and frontend in sync. Instead of manually maintaining type definitions, validation schemas, and API contracts in two places, Wayfinder makes your PHP code the single source of truth.
For teams using AI tools to generate code, Wayfinder acts as a safety net, automatically verifying that generated code matches your actual API structure. For teams working with Inertia.js or separate frontend and backend repositories, it eliminates entire categories of bugs that arise from mismatched types and outdated documentation.
As Joe mentioned during the stream, this feels like what Laravel development should have always been. With Wayfinder, your types are just there, automatically available, always in sync. It's the kind of tooling that disappears into the background, letting you focus on building features instead of maintaining infrastructure.
You can find the Wayfinder repository on GitHub, where the team welcomes issues, pull requests, and feedback as they work toward a stable 1.0 release.