> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# Vorstellung von Laravel Wayfinder

> Wir erläutern Laravel Wayfinder – das Paket, das im Inertia-Starterkit anstelle von Ziggy eingesetzt wird. Vom typsicheren Bindeglied zwischen Laravel-Backend und TypeScript-Frontend über die Unterschiede zu Ziggy, Installation und Grundgebrauch bis zu den im next-Branch entwickelten Next-Generation-Features.

## Was ist Wayfinder?

**Laravel Wayfinder** ist ein Paket, das ein Laravel-Backend reibungslos mit einem TypeScript-Frontend verbindet. Es erzeugt aus Controllern und Routen vollständig typisierte TypeScript-Funktionen, sodass Sie Laravel-Endpoints direkt als Funktion aus dem Frontend aufrufen können.

Hartkodierte URLs, manuelles Verwalten von Route-Parametern und das händische Nachziehen von Backend-Änderungen entfallen komplett.

<Info>
  Wayfinder ist im Beta (aktuell v0.1.x). Bis zum v1.0.0-Release kann sich die API noch ändern. Alle relevanten Änderungen werden im [CHANGELOG](https://github.com/laravel/wayfinder/blob/main/CHANGELOG.md) protokolliert.
</Info>

***

## Unterschiede zwischen Ziggy und Wayfinder

### Was ist Ziggy?

[Ziggy](https://github.com/tighten/ziggy) ist ein Route-Helper, der über Jahre im Laravel-Ökosystem verbreitet war. Er stellt Laravel-Routen JavaScript-seitig bereit und erzeugt URLs in der Form `route('posts.show', { id: 1 })`.

### Warum Wayfinder ihn ablöst

Da Ziggy Route-Namen und Parameter als Strings behandelt, gab es Grenzen für TypeScript. Tippfehler in Route-Namen oder falsche Parameternamen fielen erst zur Laufzeit auf.

Wayfinder ist TypeScript-first und erzeugt Controller-Methoden als **importierbare Funktionen**.

| Vergleichspunkt         | Ziggy                            | Wayfinder                              |
| ----------------------- | -------------------------------- | -------------------------------------- |
| Route-Referenzierung    | `route('posts.show', { id: 1 })` | `import { show } from "@/actions/..."` |
| Typsicherheit           | eingeschränkte Typdefinitionen   | vollständige TypeScript-Typen          |
| IDE-Support             | schwache Vervollständigung       | volle Vervollständigung und Typprüfung |
| Tree-Shaking            | alle Routen ins Bundle           | nur genutzte Routen im Bundle          |
| Zeitpunkt der Erzeugung | Laufzeit-Injektion               | statisch zur Buildzeit                 |

In den Inertia-basierten Laravel-Starterkits (React, Vue, Svelte) ist Wayfinder standardmäßig aktiv.

***

## Installation

### 1. Server-seitiges Paket per Composer installieren

```bash theme={null}
composer require laravel/wayfinder
```

### 2. Vite-Plugin per NPM installieren

```bash theme={null}
npm i -D @laravel/vite-plugin-wayfinder
```

### 3. Plugin in `vite.config.js` ergänzen

```ts theme={null}
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(),
    ],
});
```

Mit dem Vite-Plugin werden bei laufendem Dev-Server die TypeScript-Dateien bei jeder Änderung an PHP- oder Route-Dateien automatisch neu erzeugt.

***

## TypeScript-Definitionen erzeugen

Erzeugen Sie die TypeScript-Dateien mit dem Kommando `wayfinder:generate`.

```bash theme={null}
php artisan wayfinder:generate
```

Standardmäßig werden unter `resources/js` drei Verzeichnisse erzeugt.

```
resources/js/
├── actions/         # Funktionen für Controller-Actions
│   └── App/Http/Controllers/
│       └── PostController.ts
├── routes/          # Funktionen für benannte Routen
│   └── post.ts
└── wayfinder/       # Typdefinitionen
    └── types.ts
```

<Tip>
  Da die erzeugten Dateien bei jedem Build vollständig neu erzeugt werden, empfehlen wir, sie in `.gitignore` einzutragen. Schließen Sie die drei Verzeichnisse `wayfinder`, `actions` und `routes` gemeinsam aus.
</Tip>

Zum Ändern des Ausgabepfads verwenden Sie die Option `--path`.

```bash theme={null}
php artisan wayfinder:generate --path=resources/js/api
```

Sie können auch nur Controller-Actions oder nur Routen erzeugen.

```bash theme={null}
php artisan wayfinder:generate --skip-actions  # nur Routen erzeugen
php artisan wayfinder:generate --skip-routes   # nur Actions erzeugen
```

***

## Grundlegende Verwendung

### Actions importieren und nutzen

Beispiel: URL-Erzeugung für die `show`-Methode von `PostController`.

```ts theme={null}
import { show } from "@/actions/App/Http/Controllers/PostController";

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

Wenn nur die URL benötigt wird, verwenden Sie `.url()`.

```ts theme={null}
show.url(1); // "/posts/1"
```

Auch eine bestimmte HTTP-Methode ist möglich.

```ts theme={null}
show.head(1); // { url: "/posts/1", method: "head" }
```

### Übergabe von Parametern

Wayfinder-Funktionen akzeptieren verschiedene Parameterformen.

```ts theme={null}
import { update } from "@/actions/App/Http/Controllers/PostController";

// Einzelner Parameter
show(1);
show({ id: 1 });

// Mehrere Parameter
update([1, 2]);
update({ post: 1, author: 2 });
update({ post: { id: 1 }, author: { id: 2 } });
```

Wenn die Route ein Key-Binding vorgibt (`/posts/{post:slug}`), können Sie diesen Wert nutzen.

```ts theme={null}
// Route lautet /posts/{post:slug}
show("my-new-post");
show({ slug: "my-new-post" });
```

### Vollständigen Controller importieren

Sie können auch den gesamten Controller importieren und Methoden darauf aufrufen.

```ts theme={null}
import PostController from "@/actions/App/Http/Controllers/PostController";

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

<Warning>
  Beim Import des gesamten Controllers greift Tree-Shaking nicht, und alle Actions landen im Bundle. Einzelimporte halten die finale Bundle-Größe kleiner.
</Warning>

### Invokable Controller

Bei Invokable Controllern rufen Sie die importierte Funktion direkt auf.

```ts theme={null}
import StorePostController from "@/actions/App/Http/Controllers/StorePostController";

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

### Benannte Routen importieren

Für den Zugriff über Route-Namen verwenden Sie die Dateien unter `routes/`.

```ts theme={null}
import { show } from "@/routes/post";

// Wenn der Route-Name `post.show` lautet
show(1); // { url: "/posts/1", method: "get" }
```

### Query-Parameter

Alle Wayfinder-Funktionen akzeptieren `query` für zusätzliche Query-Parameter.

```ts theme={null}
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" }
```

Zum Mergen mit den aktuellen Query-Parametern der URL nutzen Sie `mergeQuery`.

```ts theme={null}
// Aktuelle 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"

// Zum Entfernen eines Parameters null angeben
show.url(1, { mergeQuery: { sort_by: null } });
// "/posts/1?page=1&q=shirt"
```

### Form-Varianten

Für den Einsatz in klassischen HTML-Formularen erzeugen Sie mit `--with-form` und verwenden die `.form`-Variante.

```bash theme={null}
php artisan wayfinder:generate --with-form
```

```tsx theme={null}
import { store, update } from "@/actions/App/Http/Controllers/PostController";

// Beispiel in React
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>
);
```

***

## Kombination aus Inertia und Wayfinder

Kombiniert mit den Formular-Helpern von Inertia versenden Sie Formulare, ohne einen einzigen URL-String zu schreiben.

```ts theme={null}
import { useForm } from "@inertiajs/react";
import { store } from "@/actions/App/Http/Controllers/PostController";

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

form.submit(store()); // Sendet POST /posts
```

Auch mit der `Link`-Komponente funktioniert es analog.

```tsx theme={null}
import { Link } from "@inertiajs/react";
import { show } from "@/actions/App/Http/Controllers/PostController";

const Nav = () => (
    <Link href={show(1)}>Beitrag ansehen</Link>
);
```

***

## Übernahme im Starterkit

Wenn Sie mit `laravel new` ein neues Projekt anlegen und React, Vue oder Svelte wählen, erhalten Sie eine Konfiguration, in der Wayfinder automatisch eingerichtet ist. Das Starterkit enthält:

* Composer-Paket `laravel/wayfinder`
* NPM-Paket `@laravel/vite-plugin-wayfinder`
* Plugin-Konfiguration in `vite.config.js`
* Eintrag der generierten Verzeichnisse in `.gitignore`

Auch die manuelle Einführung in bestehende Projekte ist mit obigen Schritten möglich.

***

## Behandlung von Reserved Words

Für Controller-Methoden mit dem Namen eines JavaScript-Schlüsselworts (z. B. `delete`, `import`) wird das Suffix `Method` angehängt.

```ts theme={null}
// Wenn der Controller eine delete-Methode besitzt
import { deleteMethod } from "@/actions/App/Http/Controllers/PostController";

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

***

## Aktueller Stand (v0.1.x)

Die aktuelle Stable-Version wird über den Branch `v0.1.x` bereitgestellt. Stand März 2026 ist die neueste Version **v0.1.15**.

### Wichtige Änderungen der v0.1.x-Reihe

| Version | Wichtigste Inhalte                                            |
| ------- | ------------------------------------------------------------- |
| v0.1.15 | Laravel-13-Support, Fix eines Blade-View-Crashes              |
| v0.1.13 | Bessere TypeScript-Strict-Kompatibilität bei Query-Parametern |
| v0.1.7  | URL-Default-Parameter frontendseitig festlegbar               |
| v0.1.6  | Vite-Plugin ergänzt                                           |
| v0.1.5  | PHP-8.2-Support, Unterstützung für Route-Cache                |
| v0.1.0  | Erste Veröffentlichung                                        |

***

## Im `next`-Branch entwickelte Next-Gen-Features

Im Branch `next` wird die nächste Version entwickelt, die den Funktionsumfang gegenüber v0.1.x deutlich erweitert.

<Warning>
  Der `next`-Branch lässt sich per `dev-next`-Constraint installieren, doch die API kann sich stark ändern. Der Einsatz in Produktion ist nicht empfohlen.
</Warning>

```bash theme={null}
composer require laravel/wayfinder:dev-next
```

### Deutlich erweiterter TypeScript-Umfang

Während v0.1.x nur Routen und Controller-Actions abdeckt, erzeugt die nächste Version alle folgenden Elemente als TypeScript.

```mermaid theme={null}
graph TD
    A["Laravel-Anwendung"] --> B["wayfinder:generate"]
    B --> C["Routes & Actions<br>Route-URL-Funktionen"]
    B --> D["Form Requests<br>Validierungstypen"]
    B --> E["Eloquent-Modelle<br>Modell-Interfaces"]
    B --> F["PHP-Enums<br>TypeScript-Konstanten"]
    B --> G["Inertia Page Props<br>Page-Prop-Typen"]
    B --> H["Broadcast-Channels<br>Channel-Typen"]
    B --> I["Broadcast-Events<br>Event-Payload-Typen"]
    B --> J["Umgebungsvariablen<br>Typen für import.meta.env"]
```

### Typen aus FormRequests

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

Aus diesem FormRequest werden folgende Typen erzeugt.

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

### Typen aus Eloquent-Modellen

```php theme={null}
class User extends Model
{
    protected $casts = [
        'email_verified_at' => 'datetime',
        'is_admin' => 'boolean',
    ];

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

Aus dem Modell werden Typen in `types.d.ts` erzeugt.

```ts theme={null}
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 zu TypeScript

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

Sowohl Typen als auch Konstanten werden generiert.

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

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

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

### Änderungen am Ausgabeverzeichnis

In v0.1.x war die Ausgabe auf `actions/`, `routes/` und `wayfinder/` aufgeteilt; in der nächsten Version wird alles unter `resources/js/wayfinder` gebündelt.

```
resources/js/wayfinder/
├── App/Http/Controllers/
│   └── PostController.ts    # Action-Funktionen (actions/ entfällt)
├── routes/
│   └── post.ts              # Benannte Routen (gleich)
├── broadcast-channels.ts    # Broadcast-Channels
├── broadcast-events.ts      # Broadcast-Events
└── types.d.ts               # Alle Typdefinitionen (statt types.ts)
```

### Wichtigste Änderungen von v0.1.x auf next

* Import-Pfad wechselt von `@/actions/...` zu `@/wayfinder/...`
* Flags `--skip-actions`, `--skip-routes`, `--with-form` entfallen und wandern in die Konfiguration
* `types.ts` heißt jetzt `types.d.ts`

***

## Fazit

Laravel Wayfinder ist die TypeScript-first-Neukonzeption der Ziggy-Funktionalität „Laravel-Routen aus JavaScript nutzen". Der Import erzeugter Funktionen bringt bei Typsicherheit, IDE-Support und Tree-Shaking erhebliche Vorteile.

Bereits v0.1.x ermöglicht typsichere Referenzen auf Routen und Controller-Actions und ist Standardteil der Inertia-basierten Laravel-Starterkits. Die im `next`-Branch entwickelte nächste Version wird zu einem umfassenderen Typ-Fundament ausgebaut, das FormRequests, Eloquent-Modelle, Enums und Inertia-Page-Props als TypeScript erzeugt.

<Card title="GitHub-Repository Laravel Wayfinder" icon="github" href="https://github.com/laravel/wayfinder">
  Quellcode, CHANGELOG und Issues finden Sie hier.
</Card>

<Card title="Vite Plugin Wayfinder" icon="bolt" href="https://github.com/laravel/vite-plugin-wayfinder">
  Details zu den Konfigurationsoptionen des Vite-Plugins.
</Card>


## Related topics

- [Vorstellung des Blaze-Pakets](/de/blog/blaze-introduction.md)
- [laravel/agent-skills – Offizielle KI-Agent-Skills-Sammlung von Laravel](/de/blog/agent-skills-introduction.md)
- [Laravel-Tests mit Pest PHP starten](/de/blog/pest-introduction.md)
- [Vue.js – Einstieg mit Inertia × Laravel](/de/blog/vue-introduction.md)
- [Laravel PAO – Output-Optimierungstool für KI-Agenten](/de/blog/pao-introduction.md)