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/1 au 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 internes
• actions/ : Fonctions correspondant à vos méthodes de contrôleurs
• routes/ : Fonctions correspondant à vos routes nommées

Note : Ces dossiers sont régénérés automatiquement. Vous pouvez les ajouter à .gitignore car 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.

Ressources#

• Documentation officielle Wayfinder
• Wayfinder et Inertia.js
• TypeScript Documentation