Wayfinder
Laravel Wayfinder : Le Type-Safety pour Vos Routes
Qu'est-ce que Wayfinder ?
Laravel Wayfinder est un outil qui génère automatiquement des fonctions TypeScript typées pour vos routes et contrôleurs Laravel. Au lieu d'écrire des URLs en dur dans votre code frontend, vous importez des fonctions qui représentent vos routes backend.
Le Problème
Traditionnellement, pour appeler une route Laravel depuis Vue.js, vous écrivez :
// ❌ Approche traditionnelle : URLs en dur
router.post('/posts/1', formData);
Problèmes avec cette approche :
- Risque de typos :
/psots/1au lieu de/posts/1 - Aucune autocomplétion : votre IDE ne vous aide pas
- Pas de vérification des paramètres : oublier un paramètre obligatoire passe inaperçu
- Refactoring impossible : renommer une route côté backend casse le frontend silencieusement
La Solution : Wayfinder
Avec Wayfinder, vous importez des fonctions générées automatiquement :
// ✅ Approche Wayfinder : fonctions typées
import { update } from '@/actions/App/Http/Controllers/PostController';
form.submit(update(1)); // Type-safe, autocomplétion, erreurs détectées
Avantages :
- ✅ Type-safety : TypeScript vérifie les paramètres à la compilation
- ✅ Autocomplétion : votre IDE suggère les routes disponibles
- ✅ Refactoring sécurisé : renommer une méthode met à jour tous les appels
- ✅ Zéro duplication : une seule source de vérité (vos contrôleurs Laravel)
Génération Automatique
Important : Avec le Vue Starter Kit, la génération des définitions TypeScript se fait automatiquement lorsque vous lancez :
composer run dev
Cette commande démarre à la fois le serveur Laravel et Vite, qui surveille vos fichiers et régénère les définitions Wayfinder à chaque modification de routes ou contrôleurs.
Fichiers générés :
Wayfinder crée trois dossiers dans resources/js/ :
wayfinder/: Fichiers de configuration internesactions/: Fonctions correspondant à vos méthodes de contrôleursroutes/: Fonctions correspondant à vos routes nommées
Note : Ces dossiers sont régénérés automatiquement. Vous pouvez les ajouter à
.gitignorecar ils ne doivent pas être versionnés.
Utilisation de Base
Importer une Action de Contrôleur
Imaginons que vous avez un contrôleur PostController avec une méthode show :
// app/Http/Controllers/PostController.php
class PostController extends Controller
{
public function show(Post $post)
{
return Inertia::render('Posts/Show', [
'post' => $post,
]);
}
}
Avec Wayfinder, vous pouvez importer cette action :
import { show } from '@/actions/App/Http/Controllers/PostController';
show(1); // Retourne : { url: "/posts/1", method: "get" }
Utilisation avec Inertia
Wayfinder s'intègre parfaitement avec Inertia.js :
Avec le composant <Link> :
<script setup lang="ts">
import { Link } from '@inertiajs/vue3';
import { show } from '@/actions/App/Http/Controllers/PostController';
</script>
<template>
<Link :href="show(1)">Voir l'article #1</Link>
</template>
Avec le Form Helper :
<script setup lang="ts">
import { useForm } from '@inertiajs/vue3';
import { store } from '@/actions/App/Http/Controllers/PostController';
const form = useForm({
title: 'Mon article',
content: 'Contenu de l\'article',
});
const submitForm = () => {
form.submit(store()); // Wayfinder résout automatiquement l'URL et la méthode
};
</script>
<template>
<form @submit.prevent="submitForm">
<!-- Vos champs de formulaire -->
</form>
</template>
Avec le composant <Form> :
<script setup lang="ts">
import { Form } from '@inertiajs/vue3';
import { store } from '@/actions/App/Http/Controllers/PostController';
</script>
<template>
<Form :action="store()">
<input type="text" name="title" />
<button type="submit">Créer</button>
</Form>
</template>
Cas d'Usage Avancés
Méthodes Multiples
Si vous souhaitez spécifier une méthode HTTP particulière :
import { update } from '@/actions/App/Http/Controllers/PostController';
update.put(1); // { url: "/posts/1", method: "put" }
update.patch(1); // { url: "/posts/1", method: "patch" }
Obtenir Uniquement l'URL
Si vous avez seulement besoin de l'URL (sans l'objet complet) :
import { show } from '@/actions/App/Http/Controllers/PostController';
show.url(1); // "/posts/1"
Paramètres Multiples
Wayfinder accepte différents formats de paramètres :
import { update } from '@/actions/App/Http/Controllers/PostController';
// Tableau de paramètres
update([1, 2]); // Route : /posts/{post}/authors/{author}
// Objet avec noms de paramètres
update({ post: 1, author: 2 });
// Objets imbriqués
update({ post: { id: 1 }, author: { id: 2 } });
Route Bindings Personnalisés
Si votre route utilise un champ personnalisé (comme slug) :
Route::get('/posts/{post:slug}', [PostController::class, 'show']);
Wayfinder détecte cela et accepte le slug directement :
import { show } from '@/actions/App/Http/Controllers/PostController';
show('mon-article'); // { url: "/posts/mon-article", method: "get" }
show({ slug: 'mon-article' }); // Alternative avec objet
Query Parameters
Vous pouvez ajouter des paramètres de requête :
import { show } from '@/actions/App/Http/Controllers/PostController';
const options = {
query: {
page: 1,
sort_by: 'name',
},
};
show.url(1, options); // "/posts/1?page=1&sort_by=name"
Routes Nommées
Wayfinder génère également des fonctions pour vos routes nommées :
Route::get('/posts/{post}', [PostController::class, 'show'])
->name('posts.show');
Vous pouvez les importer depuis le dossier routes :
import { show } from '@/routes/posts';
show(1); // { url: "/posts/1", method: "get" }
Contrôleurs Invocables
Si vous utilisez des contrôleurs invocables (avec méthode __invoke) :
class StorePostController extends Controller
{
public function __invoke(Request $request)
{
// ...
}
}
Importez directement le contrôleur et invoquez-le :
import StorePostController from '@/actions/App/Http/Controllers/StorePostController';
StorePostController(); // { url: "/posts", method: "post" }
Mots Réservés JavaScript
Si une méthode de votre contrôleur porte un nom qui est un mot réservé JavaScript (comme delete, import), Wayfinder la renomme automatiquement en ajoutant Method :
public function delete(Post $post) { ... }
Devient :
import { deleteMethod } from '@/actions/App/Http/Controllers/PostController';
deleteMethod(1); // { url: "/posts/1", method: "delete" }
Avantages de Wayfinder
Pour le Développement
- Productivité accrue : autocomplétion et suggestions de l'IDE
- Moins d'erreurs : détection des problèmes à la compilation, pas à l'exécution
- Refactoring sûr : renommer une route met à jour automatiquement tous les appels
Pour la Maintenance
- Source unique de vérité : les routes sont définies côté Laravel uniquement
- Synchronisation automatique : toute modification backend se propage au frontend
- Documentation vivante : les types TypeScript documentent les routes disponibles
Pour l'Équipe
- Moins de communication nécessaire : les nouveaux développeurs découvrent les routes via l'autocomplétion
- Standards cohérents : tout le monde utilise la même approche
- Onboarding simplifié : pas besoin de mémoriser les URLs
Bonnes Pratiques
Nommez Vos Routes
Donnez des noms explicites à vos routes pour faciliter leur utilisation :
Route::post('/posts', [PostController::class, 'store'])
->name('posts.store');
Utilisez le Route Model Binding
Laissez Laravel résoudre automatiquement les modèles :
public function show(Post $post) // Wayfinder génère : show(1)
Au lieu de :
public function show($id) // Moins clair
Explorez les Fichiers Générés
Prenez le temps d'ouvrir les fichiers dans resources/js/actions/ pour comprendre ce qui est généré. C'est une excellente façon d'apprendre.
Conclusion
Laravel Wayfinder transforme la manière dont vous appelez vos routes backend depuis votre frontend. En générant automatiquement des fonctions TypeScript typées, il élimine les erreurs de typos, facilite le refactoring, et améliore significativement l'expérience de développement.
Avec les Laravel Starter Kits, Wayfinder est déjà configuré et s'exécute automatiquement. Vous n'avez qu'à utiliser les imports pour profiter d'une intégration backend/frontend sans friction.
Note importante : Wayfinder est actuellement en Beta. L'API peut encore évoluer avant la version 1.0.0. Consultez régulièrement le changelog pour les changements.