Weave Code
Wayfinder Laravel Package
laravel/wayfinder
Laravel Wayfinder bridges your Laravel backend and TypeScript frontend by generating fully-typed, importable TypeScript functions for your controllers and routes—no more hardcoded URLs or manual syncing. Includes a Vite plugin that regenerates definitions automatically during builds and dev server r...
Laravel Wayfinder bridges your Laravel backend and TypeScript frontend by automatically generating fully-typed, importable TypeScript functions from your controllers and routes. Instead of hardcoding URLs or manually syncing backend changes, you can call Laravel endpoints directly in your client code like any other function.
- Automatic generation via the
wayfinder:generateArtisan command - Vite plugin regenerates definitions on build and file changes
- Type-safe route and controller method functions
- Configurable output with
--path,--skip-actions, and--skip-routesoptions - Zero maintenance — generated directories can be safely gitignored
Frequently asked questions about Wayfinder
- What is Laravel Wayfinder and how does it work?
- Wayfinder is a Laravel-org package that reads your registered router and controller method signatures at build time and emits fully-typed, importable TypeScript modules (the wayfinder, actions, and routes directories under resources/js). It adds no runtime dependency to either your server or your client bundle—it is pure build-time code generation. You then import the generated functions and call your Laravel endpoints like any other function instead of hardcoding URLs.
- How do I install and configure Laravel Wayfinder with Vite?
- Install the Composer package with composer require laravel/wayfinder, then add the Vite plugin with npm i -D @laravel/vite-plugin-wayfinder and register wayfinder() in your vite.config.js plugins array. The plugin runs generation during vite build and watches your routes and controllers while the dev server is running. Finally, run php artisan wayfinder:generate once to produce the initial TypeScript files.
- Which Laravel and frontend versions does Laravel Wayfinder support?
- It targets Laravel 10, 11, and 12, with Laravel 13 support landing in v0.1.14. It is designed for Vite-based builds and works with Inertia React, Vue, and Svelte, plus Blade pages with light JavaScript. It is not intended for non-Vite bundlers, separate-repo SPAs, mobile clients, or teams standardized on OpenAPI or GraphQL codegen.
- Is Laravel Wayfinder production-ready or still beta?
- Not yet—the README carries an explicit pre-1.0 warning, and the package is on 0.1.x with a parallel next branch, so generated function names, argument shapes, and the .form variant can change. Because generated code is rebuilt at build or deploy time, an upgrade typically breaks the build rather than production runtime, which is the safer failure mode. Pin the version and review the changelog on every bump before standardizing on it.
- How do I generate TypeScript definitions for my routes and controllers?
- Run php artisan wayfinder:generate. By default it writes three directories—wayfinder, actions, and routes—inside resources/js. Use --path to change the base output location, and --skip-actions or --skip-routes to generate only the controller-method side or only the route side if you want to adopt just one half of the feature. The Vite plugin also triggers generation automatically on build and on file changes.
- Should I commit or gitignore the generated wayfinder, actions, and routes folders?
- You can safely gitignore them, because the directories are completely regenerated on every build; the README explicitly notes this. Some teams prefer to commit them to keep a visible typed contract and diffs in code review. Either way, make sure generation runs before your build or deploy step so the files are never stale.
- Why does my deploy fail with "Could not load resources/js/routes/..."?
- This is the documented route:cache staleness pitfall: if a cached route file from a previous release is present when Wayfinder generates, newly added routes are silently missing, and Vite then fails with Could not load resources/js/routes/<name>. It only shows up on deploy, not locally, because local caches are usually fresh. Clear the route cache (or run route:clear) before generating in your deploy pipeline.
- How do I pass route parameters, query strings, or submit forms with generated functions?
- Generated functions are callable and return an object containing url and method, plus helpers such as .url(), .form() for form submissions, and query/mergeQuery options for query strings. Route parameters are passed as function arguments, so TypeScript enforces the correct parameter names and shapes. That means you never hand-build URLs, and the compiler catches most breakage when routes evolve.
- Does Laravel Wayfinder work for API-only backends or separate-repo SPAs?
- No. Wayfinder fits Laravel monoliths that own their frontend, especially Inertia with React or Vue, and is largely irrelevant to API-only backends or frontends in a separate repo consuming an OpenAPI spec. Its contract is that your PHP router is the source of truth, which assumes the frontend is generated in the same repository. If your client lives elsewhere, stick with OpenAPI or GraphQL codegen.
- Why did my JavaScript bundle grow after importing controller actions, and how do I fix it?
- The README flags that importing whole-controller namespaces loses tree-shaking, so the bundle can pull in more generated code than you actually call. Import individual generated functions from their specific modules instead of using wildcard namespace imports, and consider adding a lint rule to prevent the pattern. Verify the impact with your bundler's bundle analyzer, since generated files are cheap to import but not free.
Weaver
How can I help you explore Laravel packages today?