Laravel Wayfinder

Laravel has announced a new package called Wayfinder. This package will allow you to easily generate fully-typed, importable TypeScript functions for your controllers and named routes, providing devs with a seamless integration between a Laravel backend and a TypeScript frontend.

Let's learn how to use Wayfinder with the Laravel React Starter Kit. First, create a new Laravel app using the following command:

laravel new wayfinder-blog --react

Then, cd into your project, execute composer run dev, and open the app in your code editor. We're ready to start wayfinding.

Post Migration

To test things out with Wayfinder, we'll need to create a Post model and a posts migration. We can do that by running:

php artisan make:model Post -mf

The -mf flag will also create a migration and a factory.

Here is what that migration should look like:

<?php

use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

return new class extends Migration
{
    /**
     * Run the migrations.
     */
    public function up(): void
    {
        Schema::create('posts', function (Blueprint $table) {
            $table->id();
            $table->unsignedInteger('user_id');
            $table->string('title');
            $table->text('body')->nullable();
            $table->string('image')->nullable();
            $table->string('slug')->unique();
            $table->string('excerpt')->nullable();
            $table->string('type')->default('post');
            $table->string('status')->default('DRAFT');
            $table->boolean('active')->default(1);
            $table->boolean('featured')->default(0);

            // SEO COLUMNS
            $table->string('meta_title')->nullable();
            $table->string('meta_description')->nullable();
            $table->text('meta_schema')->nullable();
            $table->text('meta_data')->nullable();

            $table->timestamps();
        });
    }

    /**
     * Reverse the migrations.
     */
    public function down(): void
    {
        Schema::dropIfExists('posts');
    }
};

And the Factory should look like this:

<?php

namespace Database\Factories;

use App\Models\User;
use Illuminate\Database\Eloquent\Factories\Factory;

/**
 * @extends \Illuminate\Database\Eloquent\Factories\Factory<\App\Models\Post>
 */
class PostFactory extends Factory
{
    /**
     * Define the model's default state.
     *
     * @return array<string, mixed>
     */
    public function definition(): array
    {
        return [
            'user_id' => User::first()->id,
            'title' => fake()->sentence(),
            'body' => fake()->paragraphs(4, true),
            'slug' => fake()->unique()->slug()
        ];
    }
}

Now that we have our migration and Factory, we need to run our migration:

php artisan migrate

Adding Posts

Inside our PostFactory, we have a foreign key, user_id that references the first user in our database. We need to add a user first before we can create posts. Let's run php artisan tinker and run the following:

🤩 Our Amazing Sponsors 👇

View Website

DigitalOcean offers a simple and reliable cloud hosting solution that enables developers to get their website or application up and running quickly.

View Website

Laravel News keeps you up to date with everything Laravel. Everything from framework news to new community packages, Laravel tutorials, and more.

View Website

A Laravel Starter Kit that includes Authentication, User Dashboard, Edit Profile, and a set of UI Components. Learn more about the DevDojo sponsorship program and see your logo here to get your brand in front of thousands of developers.

App\Models\User::factory()->create()

Next, we need to create some sample posts we can play with. Let's run php artisan tinker and run the following:

App\Models\Post::factory()->count(30)->create()

Create our PostController

Let's create a new controller for our posts. We can do that by running:

php artisan make:controller PostController

This will create a new controller in the app/Http/Controllers directory.

Let's add a few methods to our Controller:

<?php

namespace App\Http\Controllers;

use App\Models\Post;
use Illuminate\Http\Request;
use Illuminate\Http\JsonResponse;

class PostController extends Controller
{
    public function index() : JsonResponse
    {
        return response()->json(Post::all());
    }

    public function show(Post $post) : JsonResponse
    {
        return response()->json($post);
    }
}

Add Post Routes

We need to specify the routes for our PostController. Add the following routes to your routes/web.php file:

// Post routes
Route::get('posts', [PostController::class, 'index'])->name('posts.index');
Route::get('posts/{post}', [PostController::class, 'show'])->name('posts.show');

Installing Wayfinder

Let's install Wayfinder by running:

composer require laravel/wayfinder

Then we need to generate our typescript definitions by running the following:

php artisan wayfinder:generate

Now, you'll see many new definitions if you go into your resources/js/actions directory. One of them will be at resources/js/actions/App/Http/Controllers/PostController.ts, which will look like the following:

import { queryParams, type QueryParams } from './../../../../wayfinder'

/** 
 * @see \App\Http\Controllers\PostController::index
 * @see app/Http/Controllers/PostController.php:11
 * @route /posts
 */
export const index = (options?: { query?: QueryParams, mergeQuery?: QueryParams }, ) => ({
    url: index.url(options),
    method: 'get',
})

index.definition = {
    methods: ['get',' head'],
    url: '\/posts',
}

/** 
 * @see \App\Http\Controllers\PostController::index
 * @see app/Http/Controllers/PostController.php:11
 * @route /posts
 */
index.url = (options?: { query?: QueryParams, mergeQuery?: QueryParams }, ) => {
    return index.definition.url + queryParams(options)
}

/** 
 * @see \App\Http\Controllers\PostController::index
 * @see app/Http/Controllers/PostController.php:11
 * @route /posts
 */
index.get = (options?: { query?: QueryParams, mergeQuery?: QueryParams }, ) => ({
    url: index.url(options),
    method: 'get',
})

/** 
 * @see \App\Http\Controllers\PostController::index
 * @see app/Http/Controllers/PostController.php:11
 * @route /posts
 */
index.head = (options?: { query?: QueryParams, mergeQuery?: QueryParams }, ) => ({
    url: index.url(options),
    method: 'head',
})

/** 
 * @see \App\Http\Controllers\PostController::show
 * @see app/Http/Controllers/PostController.php:16
 * @route /posts/{post}
 */
export const show = (args: { post: number | { id: number } } | [post: number | { id: number }] | number | { id: number }, options?: { query?: QueryParams, mergeQuery?: QueryParams }, ) => ({
    url: show.url(args, options),
    method: 'get',
})

show.definition = {
    methods: ['get',' head'],
    url: '\/posts\/{post}',
}

/** 
 * @see \App\Http\Controllers\PostController::show
 * @see app/Http/Controllers/PostController.php:16
 * @route /posts/{post}
 */
show.url = (args: { post: number | { id: number } } | [post: number | { id: number }] | number | { id: number }, options?: { query?: QueryParams, mergeQuery?: QueryParams }, ) => {
    if (typeof args === 'string' || typeof args === 'number') {
        args = { post: args }
    }

    if (typeof args === 'object' && !Array.isArray(args) && 'id' in args) {
        args = { post: args.id }
    }

    if (Array.isArray(args)) {
        args = {
            post: args[0],
        }
    }

    const parsedArgs = {
        post: typeof args.post === 'object'
            ? args.post.id
            : args.post,
    }

    return show.definition.url
            .replace('{post}', parsedArgs.post.toString())
            .replace(/\/+$/, '') + queryParams(options)
}

/** 
 * @see \App\Http\Controllers\PostController::show
 * @see app/Http/Controllers/PostController.php:16
 * @route /posts/{post}
 */
show.get = (args: { post: number | { id: number } } | [post: number | { id: number }] | number | { id: number }, options?: { query?: QueryParams, mergeQuery?: QueryParams }, ) => ({
    url: show.url(args, options),
    method: 'get',
})

/** 
 * @see \App\Http\Controllers\PostController::show
 * @see app/Http/Controllers/PostController.php:16
 * @route /posts/{post}
 */
show.head = (args: { post: number | { id: number } } | [post: number | { id: number }] | number | { id: number }, options?: { query?: QueryParams, mergeQuery?: QueryParams }, ) => ({
    url: show.url(args, options),
    method: 'head',
})

const PostController = { index, show }

export default PostController

Using our new definitions

We can now refer to this PostController by importing it into any page. Let's open up our resources/js/pages/dashboard.ts page and add the following:

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

export default function Dashboard() {
    console.log(show(1));
    return (
        ...
        ...

If you visit your dashboard page now, you should see the following console output:

{
    url: '/posts/1', 
    method: 'get'
}

This will define how we can get a post from our show method inside our PostController. If we ever decide to change a route in our application, for instance, if we were to change the following:

Route::get('posts/{post}', [PostController::class, 'show'])->name('posts.show');

To be singular post/ instead of posts/:

Route::get('post/{post}', [PostController::class, 'show'])->name('posts.show');

We don't have to do anything in our application except run the php artisan wayfinder:generate again. Wayfinder will automatically update the definitions for us.

Forms with Wayfinder

If you are using a traditional form to submit data, Wayfinder can make your life a lot easier and allow you to destructure the action and method for your form, like the following:

<form {...store.form()} className="space-y-4">

Let's cover an example of how we can use this. First, we'll need to add a new route to our routes/web.php file:

// create a post route to create new posts
Route::post('post', [PostController::class, 'store'])->name('posts.store');

We will also need to create the store() method inside our PostController. Add the following to your PostController.php file:

public function store(Request $request) : JsonResponse
{
    $post = Post::create($request->all());
    return response()->json($post);
}

You will obviously want to validate the input for the new post, but we will keep it simple for this example. Next, we want to regenerate our typescript definitions, but this time, we want to specify that we also want to include form variants:

php artisan wayfinder:generate --with-form

Now, we can call store.form() to get the form action and method. Here is an example of the full dashboard.tsx with the form:

import AppLayout from '@/layouts/app-layout';
import { type BreadcrumbItem } from '@/types';
import { Head, useForm, usePage } from '@inertiajs/react';
import { store } from "@/actions/App/Http/Controllers/PostController";

const breadcrumbs: BreadcrumbItem[] = [
    {
        title: 'Dashboard',
        href: '/dashboard',
    },
];

export default function Dashboard() {
    const props = usePage().props;
    const { data, setData, processing, errors, reset } = useForm({ user_id: 1,  title: '', body: '', slug: '' });
    return (
        <AppLayout breadcrumbs={breadcrumbs}>
            <Head title= "Dashboard"/>
            <div className="flex h-full flex-1 flex-col gap-4 rounded-xl p-4">
                <h2 className="text-2xl font-bold mb-4">Create New Post</h2>
                
                <form {...store.form()} className="space-y-4">
                    <input type="hidden" name="user_id" value={data.user_id} />
                    <input type="hidden" name="_token" value={props.csrf_token} />
                    
                    <div className="space-y-2">
                        <input 
                            placeholder= "Title"
                            name= "title"
                            value={data.title}
                            onChange={e => setData('title', e.target.value)}
                            className="w-full p-2 border rounded-md"
                            required
                        />
                        {errors.title && <div className="text-red-500">{errors.title}</div>}
                    </div>
                    
                    <div className="space-y-2">
                        <textarea 
                            placeholder= "Body"
                            name= "body"
                            value={data.body}
                            onChange={e => setData('body', e.target.value)}
                            className="w-full p-2 border rounded-md h-32"
                            required
                        />
                        {errors.body && <div className="text-red-500">{errors.body}</div>}
                    </div>
                    
                    <div className="space-y-2">
                        <input 
                            placeholder= "Slug"
                            name= "slug"
                            value={data.slug}
                            onChange={e => setData('slug', e.target.value)}
                            className="w-full p-2 border rounded-md"
                            required
                        />
                        {errors.slug && <div className="text-red-500">{errors.slug}</div>}
                    </div>
                    
                    <button 
                        type= "submit"
                        className="px-4 py-2 bg-blue-600 text-white rounded-md hover:bg-blue-700 transition-colors"
                        disabled={processing}
                    >
                        {processing ? 'Creating...': 'Create Post'}
                    </button>
                </form>
            </div>
        </AppLayout>
    );
}

Quick tip: We needed the csrf_token for our form, so you will need to add the csrf_token() to the HandleInertiaRequests middleware to make it available via usePage().props

If you visit the /dashboard page, you'll see a simple Post form that allows you to create a new post.

Conclusion

Laravel Wayfinder is a game-changer for bridging the gap between your backend routes and your frontend code. By automatically generating fully-typed TypeScript functions for your Laravel controllers and routes, it eliminates guesswork, reduces errors, and ensures your frontend stays in sync with your backend—effortlessly. Whether you're building forms or fetching data, Wayfinder brings a new level of developer experience to full-stack Laravel apps. Be sure to try Wayfinder in your next project and enjoy type-safe routing magic that just works. 🚀