Laravel Wayfinder : Créez des Parcours Utilisateur Engageants

!📌 Introduction

Laravel Wayfinder est un package révolutionnaire publié par l'équipe Laravel qui élimine le plus grand malaise dans le développement full-stack : la gestion des routes entre le backend et le frontend. Plus besoin de coder en dur les URLs, de deviner les paramètres de route ou de synchroniser manuellement les modifications du backend.

Dans cet article, je vais vous guider pas à pas à travers l'installation, la configuration et l'utilisation de Wayfinder dans une application Laravel avec Vue.js, Inertia.js et Tailwind CSS, en nous concentrant sur un cas concret : la gestion des routes de blog avec des catégories.

🔧 Installation et Configuration

1. Installation du package Laravel

composer require laravel/wayfinder

2 Installation du plugin Vite

npm i -D @laravel/vite-plugin-wayfinder

3. Configuration de Vite

Mettez à jour votre vite.config.ts :

import { defineConfig } from 'vite'

import laravel from 'laravel-vite-plugin'

import { wayfinder } from '@laravel/vite-plugin-wayfinder'

export default defineConfig({

    plugins: [

        laravel({

            input: ['resources/css/app.css', 'resources/js/app.ts'],

            refresh: true,

        }),

        wayfinder({

            path: 'resources/js/wayfinder',

            actions: 'actions',

            routes: 'routes'

        })

    ],

})

4. Génération initiale des définitions TypeScript

php artisan wayfinder:generate

Cette commande génère automatiquement des définitions TypeScript dans resources/js/wayfinder, resources/js/actions et resources/js/routes.

5. Configuration du .gitignore

Ajoutez ceci à votre .gitignore :

resources/js/wayfinder
resources/js/actions
resources/js/routes

Ces répertoires sont entièrement régénérés à chaque build, donc inutile de les versionner.

🧩 Structure de Projet Typique avec Wayfinder

Voici comment votre structure de projet pourrait ressembler après configuration :

```

resources/

└── js/

├── actions/ # Définitions des actions de contrôleur

│ └── App/

│ └── Http/

│ └── Controllers/

│ └── BlogController.ts

├── routes/ # Définitions des routes nommées

│ └── blog/

│ └── index.ts

├── pages/

│ └── BlogViews/

│ ├── BlogIndex.vue

│ └── CategoryView.vue

├── routes.ts # Configuration des routes Inertia

└── app.ts # Point d'entrée de l'application

📁 js

📁 actions

📁 components

📁 composables

📁 layouts

📁 lib

📁 pages

📁 routes

📁 blog

📁 categories

📁 comments

📁 posts

📁 tags

📄 index.ts

Étape 2 : Utiliser les routes dans TypeScript

Dans votre fichier index.ts, importez et utilisez les routes générées par Wayfinder :

mport { index, category } from '@/routes/blog';

// Exemple d'utilisation

console.log(index().url); // "/blog"

console.log(category({ category: 'tech' }).url); // "/blog/categories/tech"

Intégration avec Inertia.js et Vue.js

Étape 1 : Utiliser les routes dans les composants Vue

Dans vos composants Vue, importez les routes et utilisez-les pour les liens et les formulaires :

<script setup lang="ts">

import { Link } from '@inertiajs/vue3';

import { index, category } from '@/routes/blog';

const breadcrumbs = [

    { title: 'Blog', href: index().url },

];

</script>

<template>

    <Link :href="category({ category: 'tech' }).url">

        Voir les articles de la catégorie Tech

    </Link>

</template>

Étape 2 : Utiliser les formulaires avec Inertia

Wayfinder s’intègre parfaitement avec useForm d’Inertia :

import { useForm } from '@inertiajs/vue3';

import { store } from '@/actions/App/Http/Controllers/PostController';

const form = useForm({

    title: 'Mon nouvel article',

    content: 'Contenu de l’article...',

});
form.submit(store()); // POST vers "/posts"

Exemple complet : Blog avec Laravel, Vue.js, Inertia.js et Tailwind CSS

Étape 1 : Créer le contrôleur

Dans votre contrôleur BlogController, définissez les méthodes pour gérer les requêtes :

class BlogController extends Controller

{

    public function index(Request $request)

    {

        $posts = Post::published()

            ->with(['user:id,name', 'categories:id,name,slug', 'tags:id,name,slug'])

            ->latest()

            ->paginate(10);

        return Inertia::render('BlogViews/BlogIndex', [

            'posts' => $posts,

        ]);

    }

    public function category(Request $request, Category $category)

    {

        $posts = $category->posts()

            ->published()

            ->with(['user:id,name', 'tags:id,name,slug'])

            ->latest()

            ->paginate(10);

        return Inertia::render('BlogViews/BlogCategory', [

            'category' => $category,

            'posts' => $posts,

        ]);

    }

}

Étape 2 : Créer les vues Vue.js

Dans vos fichiers Vue, utilisez Tailwind CSS pour styliser les composants :

<template>

    <div class="container mx-auto px-4">

        <div v-for="post in posts" :key="post.id" class="mb-8">

            <Link :href="blogRoutes.show({ post: post.slug })">

                <img :src="post.cover_image" :alt="post.title" class="w-full h-48 object-cover" />

                <h2 class="text-xl font-bold mt-4">{{ post.title }}</h2>

            </Link>

        </div>

    </div>

</template>

Caractéristiques principales de Wayfinder

1. Génération automatique de fonctions TypeScript : Simplifie la consommation des routes Laravel sur le frontend.

2. Intégration avec Inertia.js : Fonctionne de manière transparente avec useForm et Link.

3. Surveillance automatique des fichiers : Met à jour les définitions TypeScript en temps réel avec Vite.

4. Typage fort : Garantit une gestion sécurisée des routes et des paramètres.

5. Flexibilité : Permet de personnaliser les chemins et les méthodes de génération.

💡 Bonnes Pratiques avec Wayfinder

1. Organisation des Imports

Créez un fichier resources/js/routes.ts pour centraliser vos imports :

// resources/js/routes.ts
export * as blogRoutes from './routes/blog';
export * as postRoutes from './routes/posts';
// Autres imports de routes...

Utilisation simplifiée dans vos composants :

<script setup lang="ts">
import { blogRoutes } from '@/routes';
// Utilisation directe de blogRoutes
</script>

2. Gestion des Erreurs

Implémentez une gestion d'erreurs robuste :

try {
    const route = blogRoutes.category('invalid-slug');
    router.visit(route.url);
} catch (error) {
    console.error('Erreur de route:', error);
    // Redirection vers une page d'erreur
    router.visit('/404');
}

3. Typage Strict pour les Paramètres

Utilisez les types générés par Wayfinder pour un typage strict :

// resources/js/wayfinder/RouteDefinition.ts
export type RouteQueryOptions = {
    query?: Record<string, string | number | boolean | null | undefined>;
    mergeQuery?: Record<string, string | number | boolean | null | undefined>;
};

4. Optimisation des Builds

Pour accélérer les builds en développement :

// vite.config.ts
export default defineConfig({
    plugins: [
        wayfinder({
            watch: process.env.NODE_ENV === 'development'
        })
    ]
});

Avantages Mesurables de Wayfinder

Conclusion : Wayfinder, un Must-Have pour les Applications Laravel Modernes

Laravel Wayfinder n'est pas simplement un outil pratique - c'est une véritable évolution dans la manière dont nous connectons le backend et le frontend dans les applications Laravel. En éliminant les problèmes chroniques de gestion des routes, il permet aux équipes de développement de se concentrer sur ce qui compte vraiment : la valeur métier.

Dans notre exemple concret avec le blog et les catégories, Wayfinder a permis :

• Une gestion simplifiée des routes dynamiques avec {category:slug}

• Une intégration transparente avec Inertia.js et Vue.js

• Un typage strict qui évite les erreurs à l'exécution

• Une refactorisation aisée des routes sans impact sur le frontend

Pour les équipes utilisant Laravel avec Vue.js et Inertia.js, Wayfinder est rapidement devenu un incontournable qui améliore significativement la productivité et la qualité du code.

Alors que Wayfinder est encore en version bêta au moment de la rédaction de cet article, son adoption rapide par la communauté Laravel témoigne de son utilité évidente. Je recommande vivement de l'intégrer dans vos nouveaux projets Laravel dès aujourd'hui, et de planifier sa migration dans vos projets existants.

Et vous, comment envisagez-vous d'utiliser Wayfinder dans vos projets ? Partagez vos expériences en commentaire !