Laravel Wayfinder: Sincronización Automática entre PHP y TypeScript

Requisitos y Compatibilidad

• PHP: 8.1 o superior

• Laravel: 10, 11 o 12

• Estado: Beta pública (enero 2026)

composer require laravel/wayfinder:dev-next

¿Qué es Laravel Wayfinder?

Laravel Wayfinder es un paquete first-party que genera TypeScript automáticamente desde tu código Laravel. Su objetivo es mantener el frontend y el backend sincronizados sin intervención manual.

Cuando trabajas con aplicaciones modernas que combinan un backend en PHP y un frontend en TypeScript, mantener ambos lados sincronizados se convierte en un proceso tedioso y propenso a errores. Si cambias una ruta, añades un campo a un modelo o modificas las reglas de validación de un formulario, debes actualizar manualmente los tipos en el frontend.

Wayfinder elimina ese problema. Analiza tu aplicación Laravel y genera automáticamente los equivalentes en TypeScript para rutas, reglas de validación, modelos, enums, eventos de broadcast y más.

¿Qué problema soluciona?

El problema fundamental es la desconexión entre PHP y TypeScript. Ambos lenguajes no pueden compartir de forma nativa tipos de datos, enums, reglas de validación u otras estructuras.

Sin Wayfinder, tienes dos opciones:

1. Mantener manualmente los tipos en ambos lados (duplicación de código, errores frecuentes)

2. No usar tipos en el frontend (pierdes las ventajas de TypeScript)

Con Wayfinder, tu código PHP se convierte en la única fuente de verdad. Cambias algo en Laravel y el frontend se actualiza automáticamente.

¿Qué genera Wayfinder?

La nueva versión en la rama next genera TypeScript para:

Routes y Controller Actions

Funciones type-safe con validación de parámetros. En lugar de hardcodear URLs, obtienes funciones con autocompletado:

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

// Genera URL y método automáticamente
PostController.index();
// { url: '/posts', method: 'get' }

// Con parámetros tipados
PostController.show({ post: 1 });
// { url: '/posts/1', method: 'get' }

// Solo la URL
PostController.show.url({ post: 42 });
// '/posts/42'

Named Routes

Acceso por nombre, igual que la función route() de Laravel:

import posts from "@/wayfinder/routes/posts";

posts.index();
// { url: '/posts', method: 'get' }

posts.show({ post: 1 });
// { url: '/posts/1', method: 'get' }

Form Requests

Los tipos se generan directamente desde tus reglas de validación:

<?php

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

Wayfinder genera:

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

Eloquent Models

Interfaces TypeScript con atributos, relaciones y accessors:

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

PHP Enums

Genera tanto tipos como constantes:

<?php

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

// Tipo para type-checking
export type PostStatus = "draft" | "published" | "archived";

// Constantes para uso en runtime
export const PostStatus = {
    Draft: "draft",
    Published: "published",
    Archived: "archived"
} as const;

Broadcast Channels y Events

Type-safety para WebSockets con Laravel Echo:

import { BroadcastChannels } from "@/wayfinder/broadcast-channels";

Echo.private(BroadcastChannels.orders(orderId))
    .listen("OrderShipped", (e) => {
        // e está completamente tipado
        console.log(e.trackingNumber);
    });

Environment Variables

Genera tipos para import.meta.env desde tu archivo .env:

interface ImportMetaEnv {
    readonly VITE_APP_NAME: string;
    readonly VITE_API_URL: string;
}

Integración con Inertia.js

Wayfinder tiene soporte de primera clase para Inertia.js. Genera tipos automáticamente para:

Page Props

Dado un controller con Inertia:

<?php

public function index(): Response
{
    return Inertia::render('Dashboard', [
        'stats' => [
            'users' => User::count(),
            'posts' => Post::count(),
        ],
    ]);
}

Wayfinder genera:

export namespace Inertia.Pages {
    export type Dashboard = Inertia.SharedData & {
        stats: {
            users: number;
            posts: number;
        };
    };
}

Shared Data

También genera tipos para los datos compartidos en HandleInertiaRequests:

export namespace Inertia {
    export type SharedData = {
        auth: {
            user: App.Models.User | null;
        };
        flash: {
            success: string | null;
            error: string | null;
        };
    };
}

Uso en componentes Vue

<script setup lang="ts">
import type { Inertia } from "@/wayfinder/types";

defineProps<Inertia.Pages.Dashboard>();
</script>

Uso con useForm

import { useForm } from "@inertiajs/vue3";
import { PostController } from "@/wayfinder/App/Http/Controllers/PostController";
import type { App } from "@/wayfinder/types";

const form = useForm<App.Http.Requests.StorePostRequest>({
    title: '',
    body: '',
});

// Type-safe: conoce URL y método
form.submit(PostController.store());

Arquitectura: Surveyor y Ranger

Wayfinder se construye sobre dos paquetes base:

Surveyor realiza análisis estático de tu aplicación Laravel. Examina controllers, models, eventos de broadcast y otras clases para extraer información sobre su estructura, métodos, propiedades y tipos de retorno.

Ranger transforma los resultados de Surveyor en DTOs estructurados y consumibles.

Wayfinder escucha a Ranger y convierte esos DTOs en TypeScript. Ambos paquetes pueden usarse de forma independiente en otros proyectos.

Instalación y Configuración

Instalar el paquete

composer require laravel/wayfinder:dev-next

Publicar la configuración

php artisan vendor:publish --tag=wayfinder-config

Configurar Vite

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

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

Generar TypeScript

php artisan wayfinder:generate

Por defecto, los archivos se generan en resources/js/wayfinder.

Sincronización entre repositorios

Si tu API Laravel y tu frontend viven en repositorios separados, Wayfinder incluye un GitHub Action que crea automáticamente pull requests en el repositorio del frontend cuando los tipos cambian en el backend.

El flujo es:

1. Modificas algo en la API (rutas, modelos, enums...)

2. El GitHub Action genera los tipos actualizados

3. Se crea un PR en el repositorio del frontend

4. Revisas, haces merge, y el frontend está sincronizado

Estado actual y futuro

La versión actual de Wayfinder (incluida en los Starter Kits de Laravel) maneja generación de rutas. La nueva versión en la rama next es mucho más ambiciosa.

El equipo está trabajando en:

• Mejor soporte para clases que implementan Arrayable y Jsonable

• Optimizaciones de rendimiento para aplicaciones grandes

• Inferencia de tipos más precisa para colecciones Eloquent

• Posible soporte para traducciones

Conclusión

Wayfinder elimina una de las mayores frustraciones del desarrollo full-stack: mantener backend y frontend sincronizados. En lugar de mantener manualmente definiciones de tipos, esquemas de validación y contratos de API en dos lugares, tu código PHP se convierte en la única fuente de verdad.

Para equipos que usan Inertia.js o mantienen repositorios separados para frontend y backend, Wayfinder elimina categorías enteras de bugs que surgen de tipos desalineados.

La beta pública está disponible en la rama next del repositorio. El equipo está buscando feedback sobre rendimiento, precisión de tipos y casos de uso que no funcionen como se espera.

Enlaces

• Repositorio Laravel Wayfinder (rama next)

• Anuncio oficial en el blog de Laravel