Laravel Wayfinder: Wenn Backend und Frontend dieselbe Sprache sprechen

Kennen Sie diese Situation? Sie schreiben fröhlich Frontend in TypeScript, aber irgendwo in den Tiefen Ihres Laravel-Backends ändert sich eine Routen-URL oder ein Parametersatz. Und dann, nach stundenlangem Debugging, stellen Sie fest, dass Ihr Frontend Anfragen ins Leere sendet oder mit falschen Daten. Es tut weh, ist frustrierend und nervt. Was wäre, wenn Ihr TypeScript-Frontend immer wüsste, welche Routen und Methoden auf dem Backend verfügbar sind, komplett mit vollständiger Typsicherheit?

Genau dieses Problem löst Laravel Wayfinder – ein frisches, aber bereits vielversprechendes Projekt vom Laravel-Team. Es ist nicht nur ein weiteres Utility, sondern eine echte Brücke, die Ihr Laravel-Backend und TypeScript-Frontend verbindet und sie zu einem einzigen, harmonisch funktionierenden Ganzen macht. Vergessen Sie manuelle Synchronisation, hartcodierte URLs und Kopfschmerzen durch geänderte Parameter. Wayfinder erledigt das automatisch für Sie.

Was ist Laravel Wayfinder und warum brauchen Sie es?

Im Wesentlichen ist Laravel Wayfinder ein Tool, das Ihre Laravel-Controller und -Routen analysiert und auf Basis dieser Informationen vollständig typisierte TypeScript-Funktionen generiert. Diese Funktionen können wie jede andere TypeScript-Funktion in Ihren Client-Code importiert und verwendet werden. Das bedeutet, dass Sie Backend-Endpunkte direkt vom Frontend aus aufrufen können, ohne sich um die Korrektheit der URL, der HTTP-Methode oder des Parametersatzes sorgen zu müssen.

Wer profitiert davon? Jeder Entwickler, der moderne Single-Page-Anwendungen (SPAs) oder Hybridprojekte erstellt, bei denen Laravel als API dient und das Frontend in React, Vue, Angular oder Svelte mit TypeScript geschrieben wird. Wenn Sie Wert auf Typsicherheit, Entwicklungsgeschwindigkeit legen und Fehler im Zusammenhang mit Frontend-Backend-Interaktion minimieren möchten, ist Wayfinder Ihre Wahl.

Wichtige Funktionen: Wie Wayfinder das Spiel verändert

Lassen Sie uns aufschlüsseln, was Wayfinder zu einem so praktischen und leistungsstarken Tool macht.

1. Automatische Generierung typsicherer Funktionen

Dies ist das Herzstück von Wayfinder. Anstatt manuell Interfaces oder Typen für jeden Endpunkt zu schreiben, erledigt Wayfinder das für Sie. Es analysiert Ihre Controller und Routen und erstellt dann entsprechende TypeScript-Dateien. Wenn Sie beispielsweise einen Controller PostController mit einer Methode show(Post $post) haben, generiert Wayfinder eine Funktion, die eine Post-ID erwartet und ein Objekt mit URL und Methode zurückgibt.

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

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

Oder wenn Sie nur die URL benötigen:

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

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

2. Flexible Behandlung von Routenparametern

Wayfinder kann verschiedene Formen der Parameterübergabe verarbeiten, was sehr praktisch ist. Sie können sie als separate Argumente, Objekte oder sogar verschachtelte Objekte übergeben, wenn die Route Model Binding nach Schlüssel verwendet (zum Beispiel {post:slug}).

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

// Одиночный параметр
show(1);
show({ id: 1 });

// Несколько параметров
update([1, 2]);
update({ post: 1, author: 2 });
update({ post: { id: 1 }, author: { id: 2 } });

// Если роут /posts/{post:slug}
show("my-new-post");
show({ slug: "my-new-post" });

Dadurch können Sie saubereren und intuitiveren Frontend-Code schreiben, ohne darüber nachdenken zu müssen, wie Laravel Parameter auf dem Backend erwartet.

3. Unterstützung für benannte Routen und aufrufbare Controller

Wayfinder beschränkt sich nicht nur auf Controller-Methoden. Es kann auch Funktionen für benannte Routen generieren, was sehr praktisch ist, wenn Sie den route() Helper in Laravel aktiv nutzen.

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

// Если именованный роут `post.show`
show(1); // { url: "/posts/1", method: "get" }

Und wenn Sie aufrufbare Controller haben (solche, die die __invoke-Methode verwenden), unterstützt Wayfinder diese ebenfalls:

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

StorePostController();

4. Vereinfachte HTML-Formulare

Selbst wenn Sie traditionelle HTML-Formulare verwenden, kann Wayfinder deren Erstellung erheblich vereinfachen. Wenn Sie die --with-form-Option während der Generierung aktivieren, erhalten Sie eine spezielle Variante von .form(), die automatisch action- und method-Attribute für Ihr <form>-Tag generiert.

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

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

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

Damit entfällt die Notwendigkeit, URLs und versteckte Felder für HTTP-Methoden außer GET und POST manuell zu erstellen.

5. Verwaltung von Query-Parametern

Müssen Sie Query-Parameter zu einer URL hinzufügen? Wayfinder bietet ein praktisches options-Objekt mit einem query- oder mergeQuery-Feld.

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

const options = {
    query: {
        page: 1,
        sort_by: "name",
    },
};

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

Und mergeQuery ermöglicht es Ihnen, Parameter mit denen zu verschmelzen, die bereits in der URL vorhanden sind, was für Pagination oder Filterung sehr praktisch ist.

6. Nahtlose Integration mit Inertia.js

Für diejenigen, die mit Inertia.js arbeiten, ist Wayfinder ein echter Fund. Die Ergebnisse von Wayfinder-Funktionen können direkt an useForm().submit() oder an href der Link-Komponente übergeben werden.

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

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

form.submit(store()); // Отправит POST запрос на `/posts`

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

const Nav = () => <Link href={show(1)}>Показать первый пост</Link>;

Dadurch wird die Backend-Interaktion in Inertia-Anwendungen maximal vereinfacht und der Code sauberer und zuverlässiger.

Wie es unter der Haube funktioniert

Laravel Wayfinder besteht aus zwei Hauptteilen:

1. Composer-Paket für Laravel: Es enthält die Logik zur Analyse Ihrer Routen und Controller sowie den php artisan wayfinder:generate-Befehl, der die Hauptarbeit der TypeScript-Dateien-Generierung durchführt. Diese Dateien werden standardmäßig in resources/js/wayfinder, resources/js/actions und resources/js/routes gespeichert.
2. Vite-Plugin @laravel/vite-plugin-wayfinder: Dieses Plugin stellt sicher, dass Ihre Routen während des Vite-Builds und bei Dateiänderungen während des Dev-Server-Betriebs automatisch neu generiert werden. Dies ist entscheidend wichtig, um die Typen aktuell zu halten.

Die generierten Dateien können bedenkenlos zu .gitignore hinzugefügt werden, da sie bei jedem Build oder beim Ausführen des Generierungsbefehls vollständig neu erstellt werden.

Praktische Anwendung: Weniger Fehler, mehr Geschwindigkeit

In meiner Praxis stoße ich oft darauf, dass die Frontend-Backend-Integration eine Fehlerquelle ist. Falsch geschriebene URL, vergessener Parameter, geänderter Routenname, der auf dem Frontend nicht synchronisiert wurde... Wayfinder löst diese Probleme an der Wurzel. Es bringt Vertrauen und Vorhersehbarkeit in den Entwicklungsprozess:

• Reduzierte Fehleranzahl: Dank der Typsicherheit werden die meisten Endpunktprobleme bereits in der TypeScript-Kompilierungsphase erkannt, nicht zur Laufzeit.
• Schnellere Entwicklung: Sie müssen nicht mehr ständig zwischen Backend und Frontend wechseln, um Routennamen oder Parameter zu überprüfen. Alles ist direkt in Ihrer IDE mit Autovervollständigung verfügbar.
• Verbesserte Code-Wartbarkeit: Der Code wird lesbarer und verständlicher, da Sie sehen können, welche Daten für jeden API-Aufruf erwartet werden.
• Einfachere Einarbeitung: Neue Teammitglieder werden es viel einfacher haben zu verstehen, wie sie mit der API interagieren müssen, dank klar definierter Typen.

Fazit: Lohnt es sich, es zu probieren?

Absolut! Laravel Wayfinder ist ein frischer Wind für alle, die Anwendungen mit Laravel und TypeScript erstellen. Es vereinfacht und verbessert den Interaktionsprozess zwischen den beiden Teilen Ihrer Anwendung erheblich. Obwohl sich das Projekt noch im Beta-Stadium befindet und sich die API ändern kann (wie die Entwickler selbst warnen), ist sein Potenzial offensichtlich. Angesichts dessen, dass es sich um ein offizielles Paket vom Laravel-Team handelt, können wir mit aktiver Entwicklung und Stabilität in der Zukunft rechnen.

Für wen ist es besonders geeignet?

• Entwickler, die Laravel und TypeScript verwenden (offensichtlich).
• Diejenigen, die Vite für Frontend-Builds verwenden.
• Projekte, die aktiv Inertia.js nutzen, wo Wayfinder besonders gut zur Geltung kommt.
• Teams, die nach höherer Codequalität und weniger Bugs streben.

Ich empfehle dringend, Laravel Wayfinder in Ihrem nächsten oder aktuellen Projekt auszuprobieren. Es kann dieses Tool werden, das Ihre Entwicklung angenehmer, effizienter und vor allem weniger fehleranfällig macht. Lassen Sie Ihr Backend und Frontend endlich dieselbe, universell verständliche Sprache sprechen!