Introducing Laravel Wayfinder

Learn about Laravel Wayfinder, adopted in the Inertia starter kits as the Ziggy replacement. Covers how it type-safely connects a Laravel backend and a TypeScript frontend, differences from Ziggy, installation and basic usage, and next-generation features evolving on the next branch.

What is Wayfinder?

Laravel Wayfinder is a package that bridges a Laravel backend and a TypeScript frontend with zero friction. It auto-generates fully typed TypeScript functions from your controllers and routes, so you can call Laravel endpoints as functions directly from your frontend code.

Hardcoded URLs, manually managed route parameters, and hand-syncing backend changes—all of that goes away.

Wayfinder is in Beta (currently v0.1.x). The API may change before v1.0.0. All notable changes are recorded in the CHANGELOG.

---

Differences between Ziggy and Wayfinder

What is Ziggy?

Ziggy has long been a widely used route helper in the Laravel ecosystem. It exposes Laravel route definitions to JavaScript so you can generate URLs like route('posts.show', { id: 1 }).

Why replace it with Wayfinder?

Because Ziggy handles route names and parameters as strings, its TypeScript integration is limited. Typos in route names or wrong parameter names show up only as runtime errors.

Wayfinder is TypeScript-first and generates controller methods as importable functions.

Comparison	Ziggy	Wayfinder
Route reference	route('posts.show', { id: 1 })	import { show } from "@/actions/..."
Type safety	Limited types	Full TypeScript types
IDE support	Weak completion	Full completion and type-checking
Tree shaking	All routes bundled	Only used routes bundled
Generation timing	Injected at runtime	Statically generated at build time

In Inertia-based Laravel starter kits (React, Vue, Svelte), Wayfinder is adopted as the standard.

---

Installation

1. Install the server-side package via Composer

composer require laravel/wayfinder

2. Install the Vite plugin via NPM

npm i -D @laravel/vite-plugin-wayfinder

3. Add the plugin to vite.config.js

import { wayfinder } from "@laravel/vite-plugin-wayfinder";
import { defineConfig } from "vite";
import laravel from "laravel-vite-plugin";

export default defineConfig({
    plugins: [
        laravel({
            input: ["resources/js/app.ts"],
            refresh: true,
        }),
        wayfinder(),
    ],
});

With the Vite plugin added, TypeScript files are automatically regenerated whenever PHP files or route files change during dev.

---

Generating TypeScript definitions

Generate TypeScript files with the wayfinder:generate command.

php artisan wayfinder:generate

By default, three directories are generated under resources/js.

resources/js/
├── actions/         # Controller action functions
│   └── App/Http/Controllers/
│       └── PostController.ts
├── routes/          # Named-route functions
│   └── post.ts
└── wayfinder/       # Type definitions
    └── types.ts

Because generated files are fully re-created on every build, add them to .gitignore. Exclude the three directories wayfinder, actions, and routes together.

To change the output location, use the --path option.

php artisan wayfinder:generate --path=resources/js/api

You can also generate only actions or only routes.

php artisan wayfinder:generate --skip-actions  # Generate only routes
php artisan wayfinder:generate --skip-routes   # Generate only actions

---

Basic usage

Importing and using an action

Here’s an example that produces the URL for PostController@show.

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

show(1);
// { url: "/posts/1", method: "get" }

Use .url() when you only need the URL.

show.url(1); // "/posts/1"

You can also specify a particular HTTP method.

show.head(1); // { url: "/posts/1", method: "head" }

Passing parameters

Wayfinder functions accept parameters in several forms.

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

// Single parameter
show(1);
show({ id: 1 });

// Multiple parameters
update([1, 2]);
update({ post: 1, author: 2 });
update({ post: { id: 1 }, author: { id: 2 } });

When the route uses key binding (/posts/{post:slug}), pass that value.

// When the route is /posts/{post:slug}
show("my-new-post");
show({ slug: "my-new-post" });

Importing a whole controller

You can also import a whole controller and call its methods.

import PostController from "@/actions/App/Http/Controllers/PostController";

PostController.show(1);
PostController.index();

Importing a whole controller defeats tree shaking, so every action ends up in the bundle. Importing individually keeps the final bundle smaller.

Single-action controllers

For single-action (invokable) controllers, call the imported function directly.

import StorePostController from "@/actions/App/Http/Controllers/StorePostController";

StorePostController(); // { url: "/posts", method: "post" }

Importing named routes

Access by route name using files under routes/.

import { show } from "@/routes/post";

// When the route name is `post.show`
show(1); // { url: "/posts/1", method: "get" }

Query parameters

Every Wayfinder function accepts a query option to add query parameters.

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

show(1, { query: { page: 1, sort_by: "name" } });
// { url: "/posts/1?page=1&sort_by=name", method: "get" }

Use mergeQuery to merge with the current URL’s query parameters.

// Current URL: /posts/1?page=1&sort_by=category&q=shirt

show.url(1, { mergeQuery: { page: 2, sort_by: "name" } });
// "/posts/1?page=2&sort_by=name&q=shirt"

// Set null to remove a parameter
show.url(1, { mergeQuery: { sort_by: null } });
// "/posts/1?page=1&q=shirt"

Form variants

For use with traditional HTML forms, generate with --with-form and use the .form variant.

php artisan wayfinder:generate --with-form

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

// React example
const Page = () => (
    <form {...store.form()}>
        {/* <form action="/posts" method="post"> */}
    </form>
);

const EditPage = () => (
    <form {...update.form(1)}>
        {/* <form action="/posts/1?_method=PATCH" method="post"> */}
    </form>
);

---

Combining Inertia and Wayfinder

Combining Inertia form helpers with Wayfinder lets you submit forms without writing any URL strings.

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

const form = useForm({ name: "My Post" });

form.submit(store()); // Submits to POST /posts

It works the same way with the Link component.

import { Link } from "@inertiajs/react";
import { show } from "@/actions/App/Http/Controllers/PostController";

const Nav = () => (
    <Link href={show(1)}>View post</Link>
);

---

Adoption in starter kits

If you create a new project with laravel new and choose React, Vue, or Svelte, you get a setup with Wayfinder configured. The starter kits include:

• The Composer package laravel/wayfinder
• The NPM package @laravel/vite-plugin-wayfinder
• Plugin configuration already applied in vite.config.js
• Generated directories already added to .gitignore

You can also add it manually to an existing project following the steps above.

---

Handling reserved words and conflicting method names

Controller methods with the same name as a JavaScript reserved word (like delete or import) get a Method suffix.

// When the controller has a `delete` method
import { deleteMethod } from "@/actions/App/Http/Controllers/PostController";

deleteMethod(1); // { url: "/posts/1", method: "delete" }

---

Current status (v0.1.x)

The current stable version is provided on the v0.1.x branch. As of March 2026, the latest version is v0.1.15.

v0.1.x main changelog

Version	Highlights
v0.1.15	Laravel 13 support, Blade view crash fix
v0.1.13	Improved TypeScript strict compatibility for query parameters
v0.1.7	Support for specifying URL default parameters on the frontend
v0.1.6	Added Vite plugin
v0.1.5	PHP 8.2 support, support for cached routes
v0.1.0	Initial release

---

Next-gen features under development on the next branch

The next branch is developing a substantially expanded next version.

The next branch can be installed with the dev-next constraint, but the API may change significantly. Not recommended for production.

composer require laravel/wayfinder:dev-next

Greatly expanded TypeScript generation

While v0.1.x targets only routes and controller actions, the next version generates all of the following as TypeScript.

Form Request TypeScript type generation

class StorePostRequest extends FormRequest
{
    public function rules(): array
    {
        return [
            'title'   => ['required', 'string', 'max:255'],
            'content' => ['required', 'string'],
            'tags'    => ['nullable', 'array'],
            'tags.*'  => ['string'],
        ];
    }
}

From the above form request, the following type is generated.

export type Request = {
    title: string;
    content: string;
    tags?: string[] | null;
};

Eloquent model type generation

class User extends Model
{
    protected $casts = [
        'email_verified_at' => 'datetime',
        'is_admin' => 'boolean',
    ];

    public function posts(): HasMany
    {
        return $this->hasMany(Post::class);
    }
}

From this model, types are generated in types.d.ts.

export namespace App.Models {
    export type User = {
        id: number;
        name: string;
        email: string;
        email_verified_at: string | null;
        is_admin: boolean;
        posts: App.Models.Post[];
    };
}

PHP Enum → TypeScript conversion

enum PostStatus: string
{
    case Draft = 'draft';
    case Published = 'published';
    case Archived = 'archived';
}

Both the type and constants are generated.

// Type (types.d.ts)
export namespace App.Enums {
    export type PostStatus = "draft" | "published" | "archived";
}

// Constants (App/Enums/PostStatus.ts)
export const Draft = "draft";
export const Published = "published";
export const Archived = "archived";

export const PostStatus = { Draft, Published, Archived } as const;

Output directory changes

In v0.1.x, output was split into three directories (actions/, routes/, wayfinder/). In the next version everything lives under resources/js/wayfinder.

resources/js/wayfinder/
├── App/Http/Controllers/
│   └── PostController.ts    # Action functions (actions/ is retired)
├── routes/
│   └── post.ts              # Named routes (same)
├── broadcast-channels.ts    # Broadcast channels
├── broadcast-events.ts      # Broadcast events
└── types.d.ts               # All type definitions (renamed from types.ts)

Main differences from v0.1.x to next

• Import paths changed from @/actions/... to @/wayfinder/...
• The --skip-actions, --skip-routes, and --with-form flags are retired in favor of a configuration file
• types.ts is renamed to types.d.ts

---

Summary

Laravel Wayfinder redesigns the “reference Laravel routes from JavaScript” feature Ziggy provided, in a TypeScript-first way. Its approach of importing generated functions delivers big improvements in type safety, IDE support, and tree shaking.

Even the current v0.1.x enables type-safe references to routes and controller actions and is adopted by default in Inertia-based Laravel starter kits. The next-branch version under development plans to evolve into a more comprehensive type-safety foundation that also generates Form Requests, Eloquent models, enums, and Inertia page props as TypeScript.

Laravel Wayfinder GitHub

Source code, CHANGELOG, and issues.

Vite Plugin Wayfinder

Detailed configuration options for the Vite plugin.